govuk-frontend
Version:
GOV.UK Frontend contains the code you need to start building a user interface for government platforms and services.
1 lines • 76.2 kB
Source Map (JSON)
{"version":3,"file":"character-count.bundle.mjs","sources":["../../../../src/govuk/common/closest-attribute-value.mjs","../../../../src/govuk/common/index.mjs","../../../../src/govuk/errors/index.mjs","../../../../src/govuk/component.mjs","../../../../src/govuk/common/configuration.mjs","../../../../src/govuk/i18n.mjs","../../../../src/govuk/components/character-count/character-count.mjs"],"sourcesContent":["/**\n * Returns the value of the given attribute closest to the given element (including itself)\n *\n * @internal\n * @param {Element} $element - The element to start walking the DOM tree up\n * @param {string} attributeName - The name of the attribute\n * @returns {string | null} Attribute value\n */\nexport function closestAttributeValue($element, attributeName) {\n const $closestElementWithAttribute = $element.closest(`[${attributeName}]`)\n return $closestElementWithAttribute\n ? $closestElementWithAttribute.getAttribute(attributeName)\n : null\n}\n","/**\n * Common helpers which do not require polyfill.\n *\n * IMPORTANT: If a helper require a polyfill, please isolate it in its own module\n * so that the polyfill can be properly tree-shaken and does not burden\n * the components that do not need that helper\n */\n\n/**\n * Get GOV.UK Frontend breakpoint value from CSS custom property\n *\n * @private\n * @param {string} name - Breakpoint name\n * @returns {{ property: string, value?: string }} Breakpoint object\n */\nexport function getBreakpoint(name) {\n const property = `--govuk-breakpoint-${name}`\n\n // Get value from `<html>` with breakpoints on CSS :root\n const value = window\n .getComputedStyle(document.documentElement)\n .getPropertyValue(property)\n\n return {\n property,\n value: value || undefined\n }\n}\n\n/**\n * Move focus to element\n *\n * Sets tabindex to -1 to make the element programmatically focusable,\n * but removes it on blur as the element doesn't need to be focused again.\n *\n * @private\n * @template {HTMLElement} FocusElement\n * @param {FocusElement} $element - HTML element\n * @param {object} [options] - Handler options\n * @param {function(this: FocusElement): void} [options.onBeforeFocus] - Callback before focus\n * @param {function(this: FocusElement): void} [options.onBlur] - Callback on blur\n */\nexport function setFocus($element, options = {}) {\n const isFocusable = $element.getAttribute('tabindex')\n\n if (!isFocusable) {\n $element.setAttribute('tabindex', '-1')\n }\n\n /**\n * Handle element focus\n */\n function onFocus() {\n $element.addEventListener('blur', onBlur, { once: true })\n }\n\n /**\n * Handle element blur\n */\n function onBlur() {\n options.onBlur?.call($element)\n\n if (!isFocusable) {\n $element.removeAttribute('tabindex')\n }\n }\n\n // Add listener to reset element on blur, after focus\n $element.addEventListener('focus', onFocus, { once: true })\n\n // Focus element\n options.onBeforeFocus?.call($element)\n $element.focus()\n}\n\n/**\n * Checks if component is already initialised\n *\n * @internal\n * @param {Element} $root - HTML element to be checked\n * @param {string} moduleName - name of component module\n * @returns {boolean} Whether component is already initialised\n */\nexport function isInitialised($root, moduleName) {\n return (\n $root instanceof HTMLElement &&\n $root.hasAttribute(`data-${moduleName}-init`)\n )\n}\n\n/**\n * Checks if GOV.UK Frontend is supported on this page\n *\n * Some browsers will load and run our JavaScript but GOV.UK Frontend\n * won't be supported.\n *\n * @param {HTMLElement | null} [$scope] - (internal) `<body>` HTML element checked for browser support\n * @returns {boolean} Whether GOV.UK Frontend is supported on this page\n */\nexport function isSupported($scope = document.body) {\n if (!$scope) {\n return false\n }\n\n return $scope.classList.contains('govuk-frontend-supported')\n}\n\n/**\n * Check for an array\n *\n * @internal\n * @param {unknown} option - Option to check\n * @returns {boolean} Whether the option is an array\n */\nfunction isArray(option) {\n return Array.isArray(option)\n}\n\n/**\n * Check for an object\n *\n * @internal\n * @template {Partial<Record<keyof ObjectType, unknown>>} ObjectType\n * @param {unknown | ObjectType} option - Option to check\n * @returns {option is ObjectType} Whether the option is an object\n */\nexport function isObject(option) {\n return !!option && typeof option === 'object' && !isArray(option)\n}\n\n/**\n * Check for valid scope\n *\n * @internal\n * @template {Element | Document} ScopeType\n * @param {unknown | ScopeType} $scope - Scope of the document to search within\n * @returns {$scope is ScopeType} Whether the scope can be queried\n */\nexport function isScope($scope) {\n return !!$scope && ($scope instanceof Element || $scope instanceof Document)\n}\n\n/**\n * Format error message\n *\n * @internal\n * @param {ComponentWithModuleName} Component - Component that threw the error\n * @param {string} message - Error message\n * @returns {string} - Formatted error message\n */\nexport function formatErrorMessage(Component, message) {\n return `${Component.moduleName}: ${message}`\n}\n\n/* eslint-disable jsdoc/valid-types --\n * `{new(...args: any[] ): object}` is not recognised as valid\n * https://github.com/gajus/eslint-plugin-jsdoc/issues/145#issuecomment-1308722878\n * https://github.com/jsdoc-type-pratt-parser/jsdoc-type-pratt-parser/issues/131\n **/\n\n/**\n * @typedef ComponentWithModuleName\n * @property {string} moduleName - Name of the component\n */\n\n/* eslint-enable jsdoc/valid-types */\n","import { formatErrorMessage, isObject } from '../common/index.mjs'\n\n/**\n * GOV.UK Frontend error\n *\n * A base class for `Error`s thrown by GOV.UK Frontend.\n *\n * It is meant to be extended into specific types of errors\n * to be thrown by our code.\n *\n * @example\n * ```js\n * class MissingRootError extends GOVUKFrontendError {\n * // Setting an explicit name is important as extending the class will not\n * // set a new `name` on the subclass. The `name` property is important\n * // to ensure intelligible error names even if the class name gets\n * // mangled by a minifier\n * name = \"MissingRootError\"\n * }\n * ```\n * @virtual\n */\nexport class GOVUKFrontendError extends Error {\n name = 'GOVUKFrontendError'\n}\n\n/**\n * Indicates that GOV.UK Frontend is not supported\n */\nexport class SupportError extends GOVUKFrontendError {\n name = 'SupportError'\n\n /**\n * Checks if GOV.UK Frontend is supported on this page\n *\n * @param {HTMLElement | null} [$scope] - HTML element `<body>` checked for browser support\n */\n constructor($scope = document.body) {\n const supportMessage =\n 'noModule' in HTMLScriptElement.prototype\n ? 'GOV.UK Frontend initialised without `<body class=\"govuk-frontend-supported\">` from template `<script>` snippet'\n : 'GOV.UK Frontend is not supported in this browser'\n\n super(\n $scope\n ? supportMessage\n : 'GOV.UK Frontend initialised without `<script type=\"module\">`'\n )\n }\n}\n\n/**\n * Indicates that a component has received an illegal configuration\n */\nexport class ConfigError extends GOVUKFrontendError {\n name = 'ConfigError'\n}\n\n/**\n * Indicates an issue with an element (possibly `null` or `undefined`)\n */\nexport class ElementError extends GOVUKFrontendError {\n name = 'ElementError'\n\n /**\n * @internal\n * @overload\n * @param {string} message - Element error message\n */\n\n /**\n * @internal\n * @overload\n * @param {ElementErrorOptions} options - Element error options\n */\n\n /**\n * @internal\n * @param {string | ElementErrorOptions} messageOrOptions - Element error message or options\n */\n constructor(messageOrOptions) {\n let message = typeof messageOrOptions === 'string' ? messageOrOptions : ''\n\n // Build message from options\n if (isObject(messageOrOptions)) {\n const { component, identifier, element, expectedType } = messageOrOptions\n\n message = identifier\n\n // Append reason\n message += element\n ? ` is not of type ${expectedType ?? 'HTMLElement'}`\n : ' not found'\n\n // Prepend with module name (optional)\n if (component) {\n message = formatErrorMessage(component, message)\n }\n }\n\n super(message)\n }\n}\n\n/**\n * Indicates that a component is already initialised\n */\nexport class InitError extends GOVUKFrontendError {\n name = 'InitError'\n\n /**\n * @internal\n * @param {ComponentWithModuleName | string} componentOrMessage - name of the component module\n */\n constructor(componentOrMessage) {\n const message =\n typeof componentOrMessage === 'string'\n ? componentOrMessage\n : formatErrorMessage(\n componentOrMessage,\n `Root element (\\`$root\\`) already initialised`\n )\n\n super(message)\n }\n}\n\n/**\n * Element error options\n *\n * @internal\n * @typedef {object} ElementErrorOptions\n * @property {Element | Document | null} [element] - The element in error (optional)\n * @property {ComponentWithModuleName} [component] - Component throwing the error (optional)\n * @property {string} identifier - An identifier that'll let the user understand which element has an error. This is whatever makes the most sense\n * @property {string} [expectedType] - The type that was expected for the identifier (optional)\n */\n\n/**\n * @import { ComponentWithModuleName } from '../common/index.mjs'\n */\n","import { isInitialised, isSupported } from './common/index.mjs'\nimport { ElementError, InitError, SupportError } from './errors/index.mjs'\n\n/**\n * Base Component class\n *\n * Centralises the behaviours shared by our components\n *\n * @virtual\n * @template {Element} [RootElementType=HTMLElement]\n */\nexport class Component {\n /**\n * @type {typeof Element}\n */\n static elementType = HTMLElement\n\n // allows Typescript user to work around the lack of types\n // in GOVUKFrontend package, Typescript is not aware of $root\n // in components that extend GOVUKFrontendComponent\n /**\n * Returns the root element of the component\n *\n * @protected\n * @returns {RootElementType} - the root element of component\n */\n get $root() {\n return this._$root\n }\n\n /**\n * @protected\n * @type {RootElementType}\n */\n _$root\n\n /**\n * Constructs a new component, validating that GOV.UK Frontend is supported\n *\n * @internal\n * @param {Element | null} [$root] - HTML element to use for component\n */\n constructor($root) {\n const childConstructor = /** @type {ChildClassConstructor} */ (\n this.constructor\n )\n\n // TypeScript does not enforce that inheriting classes will define a `moduleName`\n // (even if we add a `@virtual` `static moduleName` property to this class).\n // While we trust users to do this correctly, we do a little check to provide them\n // a helpful error message.\n //\n // After this, we'll be sure that `childConstructor` has a `moduleName`\n // as expected of the `ChildClassConstructor` we've cast `this.constructor` to.\n if (typeof childConstructor.moduleName !== 'string') {\n throw new InitError(`\\`moduleName\\` not defined in component`)\n }\n\n if (!($root instanceof childConstructor.elementType)) {\n throw new ElementError({\n element: $root,\n component: childConstructor,\n identifier: 'Root element (`$root`)',\n expectedType: childConstructor.elementType.name\n })\n } else {\n this._$root = /** @type {RootElementType} */ ($root)\n }\n\n childConstructor.checkSupport()\n\n this.checkInitialised()\n\n const moduleName = childConstructor.moduleName\n\n this.$root.setAttribute(`data-${moduleName}-init`, '')\n }\n\n /**\n * Validates whether component is already initialised\n *\n * @private\n * @throws {InitError} when component is already initialised\n */\n checkInitialised() {\n const constructor = /** @type {ChildClassConstructor} */ (this.constructor)\n const moduleName = constructor.moduleName\n\n if (moduleName && isInitialised(this.$root, moduleName)) {\n throw new InitError(constructor)\n }\n }\n\n /**\n * Validates whether components are supported\n *\n * @throws {SupportError} when the components are not supported\n */\n static checkSupport() {\n if (!isSupported()) {\n throw new SupportError()\n }\n }\n}\n\n/**\n * @typedef ChildClass\n * @property {string} moduleName - The module name that'll be looked for in the DOM when initialising the component\n */\n\n/**\n * @typedef {typeof Component & ChildClass} ChildClassConstructor\n */\n","import { Component } from '../component.mjs'\nimport { ConfigError } from '../errors/index.mjs'\n\nimport { isObject, isScope, formatErrorMessage } from './index.mjs'\n\nexport const configOverride = Symbol.for('configOverride')\n\n/**\n * Base Component class\n *\n * Centralises the behaviours shared by our components\n *\n * @virtual\n * @template {Partial<Record<keyof ConfigurationType, unknown>>} [ConfigurationType=ObjectNested]\n * @template {Element & { dataset: DOMStringMap }} [RootElementType=HTMLElement]\n * @augments Component<RootElementType>\n */\nexport class ConfigurableComponent extends Component {\n /**\n * configOverride\n *\n * Function which defines configuration overrides to prioritize\n * properties from the root element's dataset.\n *\n * It should take a subset of configuration as input and return\n * a new configuration object with properties that should be\n * overridden based on the root element's dataset. A Symbol\n * is used for indexing to prevent conflicts.\n *\n * @internal\n * @virtual\n * @param {Partial<ConfigurationType>} [param] - Configuration object\n * @returns {Partial<ConfigurationType>} return - Configuration object\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n [configOverride](param) {\n return {}\n }\n\n /**\n * Returns the root element of the component\n *\n * @protected\n * @returns {ConfigurationType} - the root element of component\n */\n get config() {\n return this._config\n }\n\n /**\n *\n * @type {ConfigurationType}\n */\n _config\n\n /**\n * Constructs a new component, validating that GOV.UK Frontend is supported\n *\n * @internal\n * @param {Element | null} [$root] - HTML element to use for component\n * @param {ConfigurationType} [config] - HTML element to use for component\n */\n constructor($root, config) {\n super($root)\n\n const childConstructor =\n /** @type {ChildClassConstructor<ConfigurationType>} */ (this.constructor)\n\n if (!isObject(childConstructor.defaults)) {\n throw new ConfigError(\n formatErrorMessage(\n childConstructor,\n 'Config passed as parameter into constructor but no defaults defined'\n )\n )\n }\n\n const datasetConfig = /** @type {ConfigurationType} */ (\n normaliseDataset(childConstructor, this._$root.dataset)\n )\n\n this._config = /** @type {ConfigurationType} */ (\n mergeConfigs(\n childConstructor.defaults,\n config ?? {},\n this[configOverride](datasetConfig),\n datasetConfig\n )\n )\n }\n}\n\n/**\n * Normalise string\n *\n * 'If it looks like a duck, and it quacks like a duck…' 🦆\n *\n * If the passed value looks like a boolean or a number, convert it to a boolean\n * or number.\n *\n * Designed to be used to convert config passed via data attributes (which are\n * always strings) into something sensible.\n *\n * @internal\n * @param {DOMStringMap[string]} value - The value to normalise\n * @param {SchemaProperty} [property] - Component schema property\n * @returns {string | boolean | number | undefined} Normalised data\n */\nexport function normaliseString(value, property) {\n const trimmedValue = value ? value.trim() : ''\n\n let output\n let outputType = property?.type\n\n // No schema type set? Determine automatically\n if (!outputType) {\n if (['true', 'false'].includes(trimmedValue)) {\n outputType = 'boolean'\n }\n\n // Empty / whitespace-only strings are considered finite so we need to check\n // the length of the trimmed string as well\n if (trimmedValue.length > 0 && isFinite(Number(trimmedValue))) {\n outputType = 'number'\n }\n }\n\n switch (outputType) {\n case 'boolean':\n output = trimmedValue === 'true'\n break\n\n case 'number':\n output = Number(trimmedValue)\n break\n\n default:\n output = value\n }\n\n return output\n}\n\n/**\n * Normalise dataset\n *\n * Loop over an object and normalise each value using {@link normaliseString},\n * optionally expanding nested `i18n.field`\n *\n * @internal\n * @template {Partial<Record<keyof ConfigurationType, unknown>>} ConfigurationType\n * @template {[keyof ConfigurationType, SchemaProperty | undefined][]} SchemaEntryType\n * @param {{ schema?: Schema<ConfigurationType>, moduleName: string }} Component - Component class\n * @param {DOMStringMap} dataset - HTML element dataset\n * @returns {ObjectNested} Normalised dataset\n */\nexport function normaliseDataset(Component, dataset) {\n if (!isObject(Component.schema)) {\n throw new ConfigError(\n formatErrorMessage(\n Component,\n 'Config passed as parameter into constructor but no schema defined'\n )\n )\n }\n\n const out = /** @type {ObjectNested} */ ({})\n const entries = /** @type {SchemaEntryType} */ (\n Object.entries(Component.schema.properties)\n )\n\n // Normalise top-level dataset ('data-*') values using schema types\n for (const entry of entries) {\n const [namespace, property] = entry\n\n // Cast the `namespace` to string so it can be used to access the dataset\n const field = namespace.toString()\n\n if (field in dataset) {\n out[field] = normaliseString(dataset[field], property)\n }\n\n /**\n * Extract and normalise nested object values automatically using\n * {@link normaliseString} but only schema object types are allowed\n */\n if (property?.type === 'object') {\n out[field] = extractConfigByNamespace(\n Component.schema,\n dataset,\n namespace\n )\n }\n }\n\n return out\n}\n\n/**\n * Normalise options passed to `initAll` or `createAll`\n *\n * @internal\n * @template {CompatibleClass} ComponentClass\n * @param {Config | CreateAllOptions<ComponentClass> | OnErrorCallback<ComponentClass> | Element | Document | null} [scopeOrOptions] - Scope of the document to search within, initialisation options or error callback function\n * @returns {CreateAllOptions<ComponentClass>} Normalised options\n */\nexport function normaliseOptions(scopeOrOptions) {\n let /** @type {Element | Document | null} */ $scope = document\n let /** @type {OnErrorCallback<ComponentClass> | undefined} */ onError\n\n // Handle options object\n if (isObject(scopeOrOptions)) {\n const options = scopeOrOptions\n\n // Scope must be valid or null\n if (isScope(options.scope) || options.scope === null) {\n $scope = options.scope\n }\n\n // Error handler must be a function\n if (typeof options.onError === 'function') {\n onError = options.onError\n }\n }\n\n if (isScope(scopeOrOptions)) {\n $scope = scopeOrOptions\n } else if (scopeOrOptions === null) {\n $scope = null\n } else if (typeof scopeOrOptions === 'function') {\n onError = scopeOrOptions\n }\n\n return {\n scope: $scope,\n onError\n }\n}\n\n/**\n * Config merging function\n *\n * Takes any number of objects and combines them together, with\n * greatest priority on the LAST item passed in.\n *\n * @internal\n * @param {...{ [key: string]: unknown }} configObjects - Config objects to merge\n * @returns {{ [key: string]: unknown }} A merged config object\n */\nexport function mergeConfigs(...configObjects) {\n // Start with an empty object as our base\n /** @type {{ [key: string]: unknown }} */\n const formattedConfigObject = {}\n\n // Loop through each of the passed objects\n for (const configObject of configObjects) {\n for (const key of Object.keys(configObject)) {\n const option = formattedConfigObject[key]\n const override = configObject[key]\n\n // Push their keys one-by-one into formattedConfigObject. Any duplicate\n // keys with object values will be merged, otherwise the new value will\n // override the existing value.\n if (isObject(option) && isObject(override)) {\n formattedConfigObject[key] = mergeConfigs(option, override)\n } else {\n // Apply override\n formattedConfigObject[key] = override\n }\n }\n }\n\n return formattedConfigObject\n}\n\n/**\n * Validate component config by schema\n *\n * Follows limited examples in JSON schema for wider support in future\n *\n * {@link https://ajv.js.org/json-schema.html#compound-keywords}\n * {@link https://ajv.js.org/packages/ajv-errors.html#single-message}\n *\n * @internal\n * @template {Partial<Record<keyof ConfigurationType, unknown>>} ConfigurationType\n * @param {Schema<ConfigurationType>} schema - The schema of a component\n * @param {ConfigurationType} config - Component config\n * @returns {string[]} List of validation errors\n */\nexport function validateConfig(schema, config) {\n const validationErrors = []\n\n // Check errors for each schema\n for (const [name, conditions] of Object.entries(schema)) {\n const errors = []\n\n // Check errors for each schema condition\n if (Array.isArray(conditions)) {\n for (const { required, errorMessage } of conditions) {\n if (!required.every((key) => !!config[key])) {\n errors.push(errorMessage) // Missing config key value\n }\n }\n\n // Check one condition passes or add errors\n if (name === 'anyOf' && !(conditions.length - errors.length >= 1)) {\n validationErrors.push(...errors)\n }\n }\n }\n\n return validationErrors\n}\n\n/**\n * Extracts keys starting with a particular namespace from dataset ('data-*')\n * object, removing the namespace in the process, normalising all values\n *\n * @internal\n * @template {Partial<Record<keyof ConfigurationType, unknown>>} ConfigurationType\n * @param {Schema<ConfigurationType>} schema - The schema of a component\n * @param {DOMStringMap} dataset - The object to extract key-value pairs from\n * @param {keyof ConfigurationType} namespace - The namespace to filter keys with\n * @returns {ObjectNested | undefined} Nested object with dot-separated key namespace removed\n */\nexport function extractConfigByNamespace(schema, dataset, namespace) {\n const property = schema.properties[namespace]\n\n // Only extract configs for object schema properties\n if (property?.type !== 'object') {\n return\n }\n\n // Add default empty config\n const newObject = /** @type {Record<typeof namespace, ObjectNested>} */ ({\n [namespace]: {}\n })\n\n for (const [key, value] of Object.entries(dataset)) {\n /** @type {ObjectNested | ObjectNested[NestedKey]} */\n let current = newObject\n\n // Split the key into parts, using . as our namespace separator\n const keyParts = key.split('.')\n\n /**\n * Create new level per part\n *\n * e.g. 'i18n.textareaDescription.other' becomes\n * `{ i18n: { textareaDescription: { other } } }`\n */\n for (const [index, name] of keyParts.entries()) {\n if (isObject(current)) {\n // Drop down to nested object until the last part\n if (index < keyParts.length - 1) {\n // New nested object (optionally) replaces existing value\n if (!isObject(current[name])) {\n current[name] = {}\n }\n\n // Drop down into new or existing nested object\n current = current[name]\n } else if (key !== namespace) {\n // Normalised value (optionally) replaces existing value\n current[name] = normaliseString(value)\n }\n }\n }\n }\n\n return newObject[namespace]\n}\n\n/**\n * @internal\n * @typedef {keyof ObjectNested} NestedKey\n * @typedef {{ [key: string]: string | boolean | number | ObjectNested | undefined }} ObjectNested\n */\n\n/**\n * Schema for component config\n *\n * @template {Partial<Record<keyof ConfigurationType, unknown>>} ConfigurationType\n * @typedef {object} Schema\n * @property {Record<keyof ConfigurationType, SchemaProperty | undefined>} properties - Schema properties\n * @property {SchemaCondition<ConfigurationType>[]} [anyOf] - List of schema conditions\n */\n\n/**\n * Schema property for component config\n *\n * @typedef {object} SchemaProperty\n * @property {'string' | 'boolean' | 'number' | 'object'} type - Property type\n */\n\n/**\n * Schema condition for component config\n *\n * @template {Partial<Record<keyof ConfigurationType, unknown>>} ConfigurationType\n * @typedef {object} SchemaCondition\n * @property {(keyof ConfigurationType)[]} required - List of required config fields\n * @property {string} errorMessage - Error message when required config fields not provided\n */\n\n/**\n * @template {Partial<Record<keyof ConfigurationType, unknown>>} [ConfigurationType=ObjectNested]\n * @typedef ChildClass\n * @property {string} moduleName - The module name that'll be looked for in the DOM when initialising the component\n * @property {Schema<ConfigurationType>} [schema] - The schema of the component configuration\n * @property {ConfigurationType} [defaults] - The default values of the configuration of the component\n */\n\n/**\n * @template {Partial<Record<keyof ConfigurationType, unknown>>} [ConfigurationType=ObjectNested]\n * @typedef {typeof Component & ChildClass<ConfigurationType>} ChildClassConstructor<ConfigurationType>\n */\n\n/**\n * @import { CompatibleClass, Config, CreateAllOptions, OnErrorCallback } from '../init.mjs'\n */\n","import { isObject } from './common/index.mjs'\n\n/**\n * Internal support for selecting messages to render, with placeholder\n * interpolation and locale-aware number formatting and pluralisation\n *\n * @internal\n */\nexport class I18n {\n translations\n locale\n\n /**\n * @internal\n * @param {{ [key: string]: string | TranslationPluralForms }} translations - Key-value pairs of the translation strings to use.\n * @param {object} [config] - Configuration options for the function.\n * @param {string | null} [config.locale] - An overriding locale for the PluralRules functionality.\n */\n constructor(translations = {}, config = {}) {\n // Make list of translations available throughout function\n this.translations = translations\n\n // The locale to use for PluralRules and NumberFormat\n this.locale = config.locale ?? (document.documentElement.lang || 'en')\n }\n\n /**\n * The most used function - takes the key for a given piece of UI text and\n * returns the appropriate string.\n *\n * @internal\n * @param {string} lookupKey - The lookup key of the string to use.\n * @param {{ [key: string]: unknown }} [options] - Any options passed with the translation string, e.g: for string interpolation.\n * @returns {string} The appropriate translation string.\n * @throws {Error} Lookup key required\n * @throws {Error} Options required for `${}` placeholders\n */\n t(lookupKey, options) {\n if (!lookupKey) {\n // Print a console error if no lookup key has been provided\n throw new Error('i18n: lookup key missing')\n }\n\n // Fetch the translation for that lookup key\n let translation = this.translations[lookupKey]\n\n // If the `count` option is set, determine which plural suffix is needed and\n // change the lookupKey to match. We check to see if it's numeric instead of\n // falsy, as this could legitimately be 0.\n if (typeof options?.count === 'number' && isObject(translation)) {\n const translationPluralForm =\n translation[this.getPluralSuffix(lookupKey, options.count)]\n\n // Update translation with plural suffix\n if (translationPluralForm) {\n translation = translationPluralForm\n }\n }\n\n if (typeof translation === 'string') {\n // Check for ${} placeholders in the translation string\n // eslint-disable-next-line @typescript-eslint/prefer-regexp-exec\n if (translation.match(/%{(.\\S+)}/)) {\n if (!options) {\n throw new Error(\n 'i18n: cannot replace placeholders in string if no option data provided'\n )\n }\n\n return this.replacePlaceholders(translation, options)\n }\n\n return translation\n }\n\n // If the key wasn't found in our translations object,\n // return the lookup key itself as the fallback\n return lookupKey\n }\n\n /**\n * Takes a translation string with placeholders, and replaces the placeholders\n * with the provided data\n *\n * @internal\n * @param {string} translationString - The translation string\n * @param {{ [key: string]: unknown }} options - Any options passed with the translation string, e.g: for string interpolation.\n * @returns {string} The translation string to output, with $\\{\\} placeholders replaced\n */\n replacePlaceholders(translationString, options) {\n const formatter = Intl.NumberFormat.supportedLocalesOf(this.locale).length\n ? new Intl.NumberFormat(this.locale)\n : undefined\n\n return translationString.replace(\n /%{(.\\S+)}/g,\n\n /**\n * Replace translation string placeholders\n *\n * @internal\n * @param {string} placeholderWithBraces - Placeholder with braces\n * @param {string} placeholderKey - Placeholder key\n * @returns {string} Placeholder value\n */\n function (placeholderWithBraces, placeholderKey) {\n if (Object.prototype.hasOwnProperty.call(options, placeholderKey)) {\n const placeholderValue = options[placeholderKey]\n\n // If a user has passed `false` as the value for the placeholder\n // treat it as though the value should not be displayed\n if (\n placeholderValue === false ||\n (typeof placeholderValue !== 'number' &&\n typeof placeholderValue !== 'string')\n ) {\n return ''\n }\n\n // If the placeholder's value is a number, localise the number formatting\n if (typeof placeholderValue === 'number') {\n return formatter\n ? formatter.format(placeholderValue)\n : `${placeholderValue}`\n }\n\n return placeholderValue\n }\n\n throw new Error(\n `i18n: no data found to replace ${placeholderWithBraces} placeholder in string`\n )\n }\n )\n }\n\n /**\n * Check to see if the browser supports Intl.PluralRules\n *\n * It requires all conditions to be met in order to be supported:\n * - The implementation of Intl supports PluralRules (NOT true in Safari 10–12)\n * - The browser/OS has plural rules for the current locale (browser dependent)\n *\n * {@link https://browsersl.ist/#q=supports+es6-module+and+not+supports+intl-pluralrules}\n *\n * @internal\n * @returns {boolean} Returns true if all conditions are met. Returns false otherwise.\n */\n hasIntlPluralRulesSupport() {\n return Boolean(\n 'PluralRules' in window.Intl &&\n Intl.PluralRules.supportedLocalesOf(this.locale).length\n )\n }\n\n /**\n * Get the appropriate suffix for the plural form.\n *\n * Uses Intl.PluralRules (or our own fallback implementation) to get the\n * 'preferred' form to use for the given count.\n *\n * Checks that a translation has been provided for that plural form – if it\n * hasn't, it'll fall back to the 'other' plural form (unless that doesn't exist\n * either, in which case an error will be thrown)\n *\n * @internal\n * @param {string} lookupKey - The lookup key of the string to use.\n * @param {number} count - Number used to determine which pluralisation to use.\n * @returns {PluralRule} The suffix associated with the correct pluralisation for this locale.\n * @throws {Error} Plural form `.other` required when preferred plural form is missing\n */\n getPluralSuffix(lookupKey, count) {\n // Validate that the number is actually a number.\n //\n // Number(count) will turn anything that can't be converted to a Number type\n // into 'NaN'. isFinite filters out NaN, as it isn't a finite number.\n // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-conversion\n count = Number(count)\n if (!isFinite(count)) {\n return 'other'\n }\n\n // Fetch the translation for that lookup key\n const translation = this.translations[lookupKey]\n\n // Check to verify that all the requirements for Intl.PluralRules are met.\n // If so, we can use that instead of our custom implementation. Otherwise,\n // use the hardcoded fallback.\n const preferredForm = this.hasIntlPluralRulesSupport()\n ? new Intl.PluralRules(this.locale).select(count)\n : 'other'\n\n // Use the correct plural form if provided\n if (isObject(translation)) {\n if (preferredForm in translation) {\n return preferredForm\n // Fall back to `other` if the plural form is missing, but log a warning\n // to the console\n } else if ('other' in translation) {\n console.warn(\n `i18n: Missing plural form \".${preferredForm}\" for \"${this.locale}\" locale. Falling back to \".other\".`\n )\n\n return 'other'\n }\n }\n\n // If the required `other` plural form is missing, all we can do is error\n throw new Error(\n `i18n: Plural form \".other\" is required for \"${this.locale}\" locale`\n )\n }\n}\n\n/**\n * Plural rule category mnemonic tags\n *\n * @internal\n * @typedef {'zero' | 'one' | 'two' | 'few' | 'many' | 'other'} PluralRule\n */\n\n/**\n * Translated message by plural rule they correspond to.\n *\n * Allows to group pluralised messages under a single key when passing\n * translations to a component's constructor\n *\n * @internal\n * @typedef {object} TranslationPluralForms\n * @property {string} [other] - General plural form\n * @property {string} [zero] - Plural form used with 0\n * @property {string} [one] - Plural form used with 1\n * @property {string} [two] - Plural form used with 2\n * @property {string} [few] - Plural form used for a few\n * @property {string} [many] - Plural form used for many\n */\n","import { closestAttributeValue } from '../../common/closest-attribute-value.mjs'\nimport {\n validateConfig,\n ConfigurableComponent,\n configOverride\n} from '../../common/configuration.mjs'\nimport { formatErrorMessage } from '../../common/index.mjs'\nimport { ConfigError, ElementError } from '../../errors/index.mjs'\nimport { I18n } from '../../i18n.mjs'\n\n/**\n * Character count component\n *\n * Tracks the number of characters or words in the `.govuk-js-character-count`\n * `<textarea>` inside the element. Displays a message with the remaining number\n * of characters/words available, or the number of characters/words in excess.\n *\n * You can configure the message to only appear after a certain percentage\n * of the available characters/words has been entered.\n *\n * @preserve\n * @augments ConfigurableComponent<CharacterCountConfig>\n */\nexport class CharacterCount extends ConfigurableComponent {\n /** @private */\n $textarea\n\n /** @private */\n count = 0\n\n /** @private */\n $visibleCountMessage\n\n /** @private */\n $screenReaderCountMessage\n\n /**\n * @private\n * @type {number | null}\n */\n lastInputTimestamp = null\n\n /** @private */\n lastInputValue = ''\n\n /**\n * @private\n * @type {number | null}\n */\n valueChecker = null\n\n /** @private */\n i18n\n\n /** @private */\n maxLength;\n\n /**\n * Character count config override\n *\n * To ensure data-attributes take complete precedence, even if they change\n * the type of count, we need to reset the `maxlength` and `maxwords` from\n * the JavaScript config.\n *\n * @internal\n * @param {CharacterCountConfig} datasetConfig - configuration specified by dataset\n * @returns {CharacterCountConfig} - configuration to override by dataset\n */\n [configOverride](datasetConfig) {\n let configOverrides = {}\n if ('maxwords' in datasetConfig || 'maxlength' in datasetConfig) {\n configOverrides = {\n maxlength: undefined,\n maxwords: undefined\n }\n }\n\n return configOverrides\n }\n\n /**\n * @param {Element | null} $root - HTML element to use for character count\n * @param {CharacterCountConfig} [config] - Character count config\n */\n constructor($root, config = {}) {\n super($root, config)\n\n const $textarea = this.$root.querySelector('.govuk-js-character-count')\n if (\n !(\n $textarea instanceof HTMLTextAreaElement ||\n $textarea instanceof HTMLInputElement\n )\n ) {\n throw new ElementError({\n component: CharacterCount,\n element: $textarea,\n expectedType: 'HTMLTextareaElement or HTMLInputElement',\n identifier: 'Form field (`.govuk-js-character-count`)'\n })\n }\n\n // Check for valid config\n const errors = validateConfig(CharacterCount.schema, this.config)\n if (errors[0]) {\n throw new ConfigError(formatErrorMessage(CharacterCount, errors[0]))\n }\n\n this.i18n = new I18n(this.config.i18n, {\n // Read the fallback if necessary rather than have it set in the defaults\n locale: closestAttributeValue(this.$root, 'lang')\n })\n\n // Determine the limit attribute (characters or words)\n this.maxLength = this.config.maxwords ?? this.config.maxlength ?? Infinity\n\n this.$textarea = $textarea\n\n const textareaDescriptionId = `${this.$textarea.id}-info`\n const $textareaDescription = document.getElementById(textareaDescriptionId)\n if (!$textareaDescription) {\n throw new ElementError({\n component: CharacterCount,\n element: $textareaDescription,\n identifier: `Count message (\\`id=\"${textareaDescriptionId}\"\\`)`\n })\n }\n\n // Pre-existing validation error rendered from server\n this.$errorMessage = this.$root.querySelector('.govuk-error-message')\n\n // Inject a description for the textarea if none is present already\n // for when the component was rendered with no maxlength, maxwords\n // nor custom textareaDescriptionText\n // eslint-disable-next-line @typescript-eslint/prefer-regexp-exec\n if ($textareaDescription.textContent.match(/^\\s*$/)) {\n $textareaDescription.textContent = this.i18n.t('textareaDescription', {\n count: this.maxLength\n })\n }\n\n // Move the textarea description to be immediately after the textarea\n // Kept for backwards compatibility\n this.$textarea.insertAdjacentElement('afterend', $textareaDescription)\n\n // Create the *screen reader* specific live-updating counter\n // This doesn't need any styling classes, as it is never visible\n const $screenReaderCountMessage = document.createElement('div')\n $screenReaderCountMessage.className =\n 'govuk-character-count__sr-status govuk-visually-hidden'\n $screenReaderCountMessage.setAttribute('aria-live', 'polite')\n this.$screenReaderCountMessage = $screenReaderCountMessage\n $textareaDescription.insertAdjacentElement(\n 'afterend',\n $screenReaderCountMessage\n )\n\n // Create our live-updating counter element, copying the classes from the\n // textarea description for backwards compatibility as these may have been\n // configured\n const $visibleCountMessage = document.createElement('div')\n $visibleCountMessage.className = $textareaDescription.className\n $visibleCountMessage.classList.add('govuk-character-count__status')\n $visibleCountMessage.setAttribute('aria-hidden', 'true')\n this.$visibleCountMessage = $visibleCountMessage\n $textareaDescription.insertAdjacentElement('afterend', $visibleCountMessage)\n\n // Hide the textarea description\n $textareaDescription.classList.add('govuk-visually-hidden')\n\n // Remove hard limit if set\n this.$textarea.removeAttribute('maxlength')\n\n this.bindChangeEvents()\n\n // When the page is restored after navigating 'back' in some browsers the\n // state of form controls is not restored until *after* the DOMContentLoaded\n // event is fired, so we need to sync after the pageshow event.\n window.addEventListener('pageshow', () => {\n // If the current value of the textarea is the same as what's\n // in the HTML, don't re-run when users have not edited the field yet\n // (new page load or BF cache navigation without having edited).\n if (this.$textarea.value !== this.$textarea.textContent) {\n this.updateCount()\n this.updateCountMessage()\n }\n })\n\n // Although we've set up handlers to sync state on the pageshow event, init\n // could be called after those events have fired, for example if they are\n // added to the page dynamically, so update now too.\n this.updateCount()\n this.updateCountMessage()\n }\n\n /**\n * Bind change events\n *\n * Set up event listeners on the $textarea so that the count messages update\n * when the user types.\n *\n * @private\n */\n bindChangeEvents() {\n this.$textarea.addEventListener('input', () => this.handleInput())\n\n // Bind focus/blur events to start/stop polling\n this.$textarea.addEventListener('focus', () => this.handleFocus())\n this.$textarea.addEventListener('blur', () => this.handleBlur())\n }\n\n /**\n * Handle input event\n *\n * Update the visible character counter and keep track of when the last update\n * happened for each keypress\n *\n * @private\n */\n handleInput() {\n this.updateCount()\n this.updateVisibleCountMessage()\n this.lastInputTimestamp = Date.now()\n }\n\n /**\n * Handle focus event\n *\n * Speech recognition software such as Dragon NaturallySpeaking will modify\n * the fields by directly changing its `value`. These changes don't trigger\n * events in JavaScript, so we need to poll to handle when and if they occur.\n *\n * Once the keyup event hasn't been detected for at least 1000 ms (1s), check\n * if the textarea value has changed and update the count message if it has.\n *\n * This is so that the update triggered by the manual comparison doesn't\n * conflict with debounced KeyboardEvent updates.\n *\n * @private\n */\n handleFocus() {\n this.valueChecker = window.setInterval(() => {\n if (\n !this.lastInputTimestamp ||\n Date.now() - 500 >= this.lastInputTimestamp\n ) {\n this.updateIfValueChanged()\n }\n }, 1000)\n }\n\n /**\n * Handle blur event\n *\n * Stop checking the textarea value once the textarea no longer has focus\n *\n * @private\n */\n handleBlur() {\n // Cancel value checking on blur\n if (this.valueChecker) {\n window.clearInterval(this.valueChecker)\n }\n }\n\n /**\n * Update count message if textarea value has changed\n *\n * @private\n */\n updateIfValueChanged() {\n if (this.$textarea.value !== this.lastInputValue) {\n this.lastInputValue = this.$textarea.value\n this.updateCountMessage()\n }\n }\n\n /**\n * Update count message\n *\n * Helper function to update both the visible and screen reader-specific\n * counters simultaneously (e.g. on init)\n *\n * @private\n */\n updateCountMessage() {\n this.updateVisibleCountMessage()\n this.updateScreenReaderCountMessage()\n }\n\n /**\n * Update visible count message\n *\n * @private\n */\n updateVisibleCountMessage() {\n const remainingNumber = this.maxLength - this.count\n const isError = remainingNumber < 0\n\n // If input is over the threshold, remove the disabled class which renders\n // the counter invisible.\n this.$visibleCountMessage.classList.toggle(\n 'govuk-character-count__message--disabled',\n !this.isOverThreshold()\n )\n\n // Update styles\n if (!this.$errorMessage) {\n // Only toggle the textarea error class if there isn't an error message\n // already, as it may be unrelated to the limit (eg: allowed characters)\n // and would set the border colour back to black.\n this.$textarea.classList.toggle('govuk-textarea--error', isError)\n }\n this.$visibleCountMessage.classList.toggle('govuk-error-message', isError)\n this.$visibleCountMessage.classList.toggle('govuk-hint', !isError)\n\n // Update message\n this.$visibleCountMessage.textContent = this.getCountMessage()\n }\n\n /**\n * Update screen reader count message\n *\n * @private\n */\n updateScreenReaderCountMessage() {\n // If over the threshold, remove the aria-hidden attribute, allowing screen\n // readers to announce the content of the element.\n if (this.isOverThreshold()) {\n this.$screenReaderCountMessage.removeAttribute('aria-hidden')\n } else {\n this.$screenReaderCountMessage.setAttribute('aria-hidden', 'true')\n }\n\n // Update message\n this.$screenReaderCountMessage.textContent = this.getCountMessage()\n }\n\n /**\n * Count the number of characters (or words, if `config.maxwords` is set)\n * in the given text, and update the component-wide count\n *\n * @private\n */\n updateCount() {\n const text = this.$textarea.value\n\n if (this.config.maxwords) {\n const tokens = text.match(/\\S+/g) ?? [] // Matches consecutive non-whitespace chars\n this.count = tokens.length\n return\n }\n\n this.count = text.length\n }\n\n /**\n * Get count message\n *\n * @private\n * @returns {string} Status message\n */\n getCountMessage() {\n const remainingNumber = this.maxLength - this.count\n const countType = this.config.maxwords ? 'words' : 'characters'\n return this.formatCountMessage(remainingNumber, countType)\n }\n\n /**\n * Formats the message shown to users according to what's counted\n * and how many remain\n *\n * @private\n * @param {number} remainingNumber - The number of words/characaters remaining\n * @param {string} countType - \"words\" or \"characters\"\n * @returns {string} Status message\n */\n formatCountMessage(remainingNumber, countType) {\n if (remainingNumber === 0) {\n return this.i18n.t(`${countType}AtLimit`)\n }\n\n const translationKeySuffix =\n remainingNumber < 0 ? 'OverLimit' : 'UnderLimit'\n\n return this.i18n.t(`${countType}${translationKeySuffix}`, {\n count: Math.abs(remainingNumber)\n })\n }\n\n /**\n * Check if count is over threshold\n *\n * Checks whether the value is over the configured threshold for the input.\n * If there is no configured threshold, it is set to 0 and this function will\n * always return true.\n *\n * @private\n * @returns {boolean} true if the current count is over the config.threshold\n * (or no threshold is set)\n */\n isOverThreshold() {\n // No threshold means we're always above threshold so save some computation\n if (!this.config.threshold) {\n return true\n }\n\n // Determine the remaining number of characters/words\n const currentLength = this.count\n const maxLength = this.maxLength\n\n const thresholdValue = (maxLength * this.config.threshold) / 100\n\n return thresholdValue <= currentLength\n }\n\n /**\n * Name for the component used when initialising using data-module attributes.\n */\n static moduleName = 'govuk-character-count'\n\n /**\n * Character count default config\n *\n * @see {@link CharacterCountConfig}\n * @constant\n * @type {CharacterCountConfig}\n */\n static defaults = Object.freeze({\n threshold: 0,\n i18n: {\n // Characters\n charactersUnderLimit: {\n one: 'You have %{count} character remaining',\n other: 'You have %{count} characters remaining'\n },\n charactersAtLimit: 'You have 0 characters remaining',\n charactersOverLimit: {\n one: 'You have %{count} character too many',\n other: 'You have %{count} characters too many'\n },\n // Words\n wordsUnderLimit: {\n one: 'You have %{count} word remaining',\n other: 'You have %{count} words remaining'\n },\n wordsAtLimit: 'You have 0 words remaining',\n wordsOverLimit: {\n one: 'You have %{count} word too many',\n other: 'You have %{count} words too many'\n },\n textareaDescription: {\n other: ''\n }\n }\n })\n\n /**\n * Character count config schema\n *\n * @constant\n * @satisfies {Schema<CharacterCountConfig>}\n */\n static schema = Object.freeze({\n properties: {\n i18n: { type: 'object' },\n maxwords: { type: 'number' },\n maxlength: { type: 'number' },\n threshold: { type: 'number' }\n },\n anyOf: [\n {\n required: ['maxwords'],\n errorMessage: 'Either \"maxlength\" or \"maxwords\" must be provided'\n },\n {\n required: ['maxlength'],\n errorMessage: 'Either \"maxlength\" or \"maxwords\" must be provided'\n }\n ]\n })\n}\n\n/**\n * Character count config\n *\n * @see {@link CharacterCount.defaults}\n * @typedef {object} CharacterCountConfig\n * @property {number} [maxlength] - The maximum number of charac