Use JSDoc tag @internal for I18n and common helpers

Since we mock `.hasIntlPluralRulesSupport()` and call `.getPluralSuffix()` in tests (and others) we can’t mark them as `@private` without compiler warnings

Ideally we should only test public interfaces

packages/govuk-frontend/src/govuk/common/closest-attribute-value.mjs

@@ -1,7 +1,7 @@
 /**
  * Returns the value of the given attribute closest to the given element (including itself)
  *
- * @private
+ * @internal
  * @param {Element} $element - The element to start walking the DOM tree up
  * @param {string} attributeName - The name of the attribute
  * @returns {string | null} Attribute value

packages/govuk-frontend/src/govuk/common/index.mjs

@@ -4,8 +4,6 @@
  * IMPORTANT: If a helper require a polyfill, please isolate it in its own module
  * so that the polyfill can be properly tree-shaken and does not burden
  * the components that do not need that helper
- *
- * @module common/index
  */
 
 /**
@@ -15,7 +13,7 @@
  * (e.g. \{'i18n.showSection': 'Show section'\}) and combines them together, with
  * greatest priority on the LAST item passed in.
  *
- * @private
+ * @internal
  * @returns {{ [key: string]: unknown }} A flattened object of key-value pairs.
  */
 export function mergeConfigs (/* configObject1, configObject2, ...configObjects */) {
@@ -25,6 +23,7 @@ export function mergeConfigs (/* configObject1, configObject2, ...configObjects
    * each of our objects, nor transform our dataset from a flat list into a
    * nested object.
    *
+   * @internal
    * @param {{ [key: string]: unknown }} configObject - Deeply nested object
    * @returns {{ [key: string]: unknown }} Flattened object with dot-separated keys
    */
@@ -38,6 +37,7 @@ export function mergeConfigs (/* configObject1, configObject2, ...configObjects
      * depth in the object. At each level we prepend the previous level names to
      * the key using `prefix`.
      *
+     * @internal
      * @param {Partial<{ [key: string]: unknown }>} obj - Object to flatten
      * @param {string} [prefix] - Optional dot-separated prefix
      */
@@ -90,7 +90,7 @@ export function mergeConfigs (/* configObject1, configObject2, ...configObjects
  * Extracts keys starting with a particular namespace from a flattened config
  * object, removing the namespace in the process.
  *
- * @private
+ * @internal
  * @param {{ [key: string]: unknown }} configObject - The object to extract key-value pairs from.
  * @param {string} namespace - The namespace to filter keys with.
  * @returns {{ [key: string]: unknown }} Flattened object with dot-separated key namespace removed

packages/govuk-frontend/src/govuk/common/normalise-dataset.mjs

@@ -9,7 +9,7 @@
  * Designed to be used to convert config passed via data attributes (which are
  * always strings) into something sensible.
  *
- * @private
+ * @internal
  * @param {string} value - The value to normalise
  * @returns {string | boolean | number | undefined} Normalised data
  */
@@ -42,7 +42,7 @@ export function normaliseString (value) {
  *
  * Loop over an object and normalise each value using normaliseData function
  *
- * @private
+ * @internal
  * @param {DOMStringMap} dataset - HTML element dataset
  * @returns {{ [key: string]: unknown }} Normalised dataset
  */

packages/govuk-frontend/src/govuk/i18n.mjs

@@ -2,13 +2,14 @@
  * Internal support for selecting messages to render, with placeholder
  * interpolation and locale-aware number formatting and pluralisation
  *
- * @private
+ * @internal
  */
 export class I18n {
   translations
   locale
 
   /**
+   * @internal
    * @param {{ [key: string]: unknown }} translations - Key-value pairs of the translation strings to use.
    * @param {object} [config] - Configuration options for the function.
    * @param {string} [config.locale] - An overriding locale for the PluralRules functionality.
@@ -25,6 +26,7 @@ export class I18n {
    * The most used function - takes the key for a given piece of UI text and
    * returns the appropriate string.
    *
+   * @internal
    * @param {string} lookupKey - The lookup key of the string to use.
    * @param {{ [key: string]: unknown }} [options] - Any options passed with the translation string, e.g: for string interpolation.
    * @returns {string} The appropriate translation string.
@@ -70,6 +72,7 @@ export class I18n {
    * Takes a translation string with placeholders, and replaces the placeholders
    * with the provided data
    *
+   * @internal
    * @param {string} translationString - The translation string
    * @param {{ [key: string]: unknown }} options - Any options passed with the translation string, e.g: for string interpolation.
    * @returns {string} The translation string to output, with $\{\} placeholders replaced
@@ -88,6 +91,7 @@ export class I18n {
       /**
        * Replace translation string placeholders
        *
+       * @internal
        * @param {string} placeholderWithBraces - Placeholder with braces
        * @param {string} placeholderKey - Placeholder key
        * @returns {string} Placeholder value
@@ -125,6 +129,7 @@ export class I18n {
    * - The implementation of Intl supports PluralRules (NOT true in IE11)
    * - The browser/OS has plural rules for the current locale (browser dependent)
    *
+   * @internal
    * @returns {boolean} Returns true if all conditions are met. Returns false otherwise.
    */
   hasIntlPluralRulesSupport () {
@@ -139,6 +144,7 @@ export class I18n {
    * - The implementation of Intl supports NumberFormat (also true in IE11)
    * - The browser/OS has number formatting rules for the current locale (browser dependent)
    *
+   * @internal
    * @returns {boolean} Returns true if all conditions are met. Returns false otherwise.
    */
   hasIntlNumberFormatSupport () {
@@ -155,6 +161,7 @@ export class I18n {
    * hasn't, it'll fall back to the 'other' plural form (unless that doesn't exist
    * either, in which case an error will be thrown)
    *
+   * @internal
    * @param {string} lookupKey - The lookup key of the string to use.
    * @param {number} count - Number used to determine which pluralisation to use.
    * @returns {PluralRule} The suffix associated with the correct pluralisation for this locale.
@@ -204,6 +211,7 @@ export class I18n {
    * This is split out into a separate function to make it easier to test the
    * fallback behaviour in an environment where Intl.PluralRules exists.
    *
+   * @internal
    * @param {number} count - Number used to determine which pluralisation to use.
    * @returns {PluralRule} The pluralisation form for count in this locale.
    */
@@ -229,6 +237,7 @@ export class I18n {
    * regardless of region. There are exceptions, however, (e.g. Portuguese) so
    * this searches by both the full and shortened locale codes, just to be sure.
    *
+   * @internal
    * @returns {string | undefined} The name of the pluralisation rule to use (a key for one
    *   of the functions in this.pluralRules)
    */
@@ -280,6 +289,7 @@ export class I18n {
    * Spanish: European Portuguese (pt-PT), Italian (it), Spanish (es)
    * Welsh: Welsh (cy)
    *
+   * @internal
    * @type {{ [key: string]: string[] }}
    */
   static pluralRulesMap = {
@@ -308,6 +318,7 @@ export class I18n {
    *
    * The count must be a positive integer. Negative numbers and decimals aren't accounted for
    *
+   * @internal
    * @type {{ [key: string]: (count: number) => PluralRule }}
    */
   static pluralRules = {
@@ -372,6 +383,7 @@ export class I18n {
 /**
  * Plural rule category mnemonic tags
  *
+ * @internal
  * @typedef {'zero' | 'one' | 'two' | 'few' | 'many' | 'other'} PluralRule
  */
 
@@ -381,6 +393,7 @@ export class I18n {
  * Allows to group pluralised messages under a single key when passing
  * translations to a component's constructor
  *
+ * @internal
  * @typedef {object} TranslationPluralForms
  * @property {string} [other] - General plural form
  * @property {string} [zero] - Plural form used with 0