Updates for GOV.UK Frontend v5.0.0

.eslintrc.js

@@ -13,6 +13,7 @@ module.exports = {
       extends: [
         'eslint:recommended',
         'plugin:import/recommended',
+        'plugin:jsdoc/recommended-typescript-flavor',
         'plugin:n/recommended',
         'plugin:promise/recommended',
         'prettier'
@@ -27,7 +28,7 @@ module.exports = {
       parserOptions: {
         ecmaVersion: 'latest'
       },
-      plugins: ['import', 'n', 'promise'],
+      plugins: ['import', 'jsdoc', 'n', 'promise'],
       rules: {
         // Check import or require statements are A-Z ordered
         'import/order': [
@@ -36,7 +37,50 @@ module.exports = {
             alphabetize: { order: 'asc' },
             'newlines-between': 'always'
           }
-        ]
+        ],
+
+        // JSDoc blocks are optional by default
+        'jsdoc/require-jsdoc': 'off',
+
+        // Check for valid formatting
+        'jsdoc/check-line-alignment': [
+          'warn',
+          'never',
+          {
+            wrapIndent: '  '
+          }
+        ],
+
+        // Add unknown @jest-environment tag name
+        'jsdoc/check-tag-names': [
+          'warn',
+          {
+            definedTags: ['jest-environment']
+          }
+        ],
+
+        // Require hyphens before param description
+        // Aligns with TSDoc style: https://tsdoc.org/pages/tags/param/
+        'jsdoc/require-hyphen-before-param-description': 'warn',
+
+        // Maintain new line after description
+        'jsdoc/tag-lines': [
+          'warn',
+          'never',
+          {
+            startLines: 1
+          }
+        ],
+
+        // Automatically use template strings
+        'no-useless-concat': 'error',
+        'prefer-template': 'error'
+      },
+      settings: {
+        jsdoc: {
+          // Allows us to use type declarations that exist in our dependencies
+          mode: 'typescript'
+        }
       }
     },
     {

.github/dependabot.yml

@@ -19,6 +19,7 @@ updates:
           - 'standard'
           - 'stylelint'
           - 'stylelint-*'
+          - 'typescript'
 
       metalsmith:
         patterns:
@@ -41,10 +42,22 @@ updates:
       test:
         patterns:
           - '@axe-core/*'
+          - '@jest/*'
+          - '@types/jest'
+          - '@types/jest-*'
           - 'jest'
           - 'jest-*'
           - 'puppeteer'
 
+      types:
+        patterns:
+          - '@types/*'
+
+        # Exclude packages in other groups
+        exclude-patterns:
+          - '@types/jest'
+          - '@types/jest-*'
+
     reviewers:
       - alphagov/design-system-developers
 

.github/workflows/test.yaml

@@ -96,6 +96,9 @@ jobs:
             run: npm run lint:prettier
             continue-on-error: true
 
+          - description: TypeScript compiler
+            run: npm run lint:types -- --pretty
+
           - description: JavaScript tests
             run: npx jest --color --maxWorkers=2
 

__tests__/component-options.test.js

@@ -77,7 +77,7 @@ describe('Component page', () => {
     await goTo(page, '/components/back-link/#options-back-link-example')
 
     // Check if example's macro options details element is open
-    await page.waitForSelector('#options-back-link-example-details[open=open]')
+    await page.waitForSelector('#options-back-link-example-details[open]')
 
     // Check if the example has been scrolled into the viewport
     const $example = await page.$('#options-back-link-example-details')
@@ -91,7 +91,7 @@ describe('Component page', () => {
     )
 
     // Check if example's macro options details element is open
-    await page.waitForSelector('#options-text-input-example-details[open=open]')
+    await page.waitForSelector('#options-text-input-example-details[open]')
 
     // Check if the example has been scrolled into the viewport
     const $example = await page.$('#options-text-input-example--label')

__tests__/cookie-functions.test.mjs

@@ -17,12 +17,8 @@ describe('Cookie settings', () => {
     const cookies = document.cookie.split(';')
     cookies.forEach(function (cookie) {
       const name = cookie.split('=')[0]
-      document.cookie = name + '=;expires=Thu, 01 Jan 1970 00:00:00 GMT;path=/'
-      document.cookie =
-        name +
-        '=;expires=Thu, 01 Jan 1970 00:00:00 GMT;domain=' +
-        window.location.hostname +
-        ';path=/'
+      document.cookie = `${name}=;expires=Thu, 01 Jan 1970 00:00:00 GMT;path=/`
+      document.cookie = `${name}=;expires=Thu, 01 Jan 1970 00:00:00 GMT;domain=${window.location.hostname};path=/`
     })
   })
 

lib/colours.js

@@ -22,7 +22,7 @@ function getColourFromSass(sass, variableName) {
  * Extracts the colour palette from the $govuk-colours map defined in
  * settings/_colours-palette.scss in GOV.UK Frontend
  *
- * @return Object mapping colour names to their hexadecimal values
+ * @returns Object mapping colour names to their hexadecimal values
  */
 
 const palette = function () {
@@ -63,9 +63,8 @@ const palette = function () {
  * }
  * ```
  *
- * @return Object containing 'groups' of colours
+ * @returns {{ [color: string]: { name: string, notes?: string }[] }} Groups of colours
  */
-
 const applied = function () {
   const data = require('../data/colours.json')
   const sass = parseSCSS('_colours-applied.scss')

lib/extract-page-headings/index.js

@@ -5,7 +5,6 @@ const { slugify } = require('../nunjucks/filters')
 /**
  * Metalsmith extract headings plugin
  *
- * @param {string[]} config.pattern - File match glob patterns
  * @returns {import('metalsmith').Plugin} Metalsmith plugin
  */
 const extractPageHeadings = () => (files, metalsmith, done) => {

lib/fingerprints/index.js

@@ -68,6 +68,7 @@ const hashAssets = (config) => (files, metalsmith, done) => {
  *
  * @param {import('metalsmith').Files} files - Metalsmith files
  * @param {import('metalsmith')} metalsmith - Metalsmith builder
+ * @returns {(pathAsset: string) => { path: string; hash: string; }} File hasher
  */
 const hashAsset = (files, metalsmith) => {
   const metadata = metalsmith.metadata()

lib/generate-sitemap.js

@@ -14,18 +14,19 @@ const removeEmptyKeys = (obj) => {
 /**
  * Plugin to generate a sitemap
  *
+ * See Sitemaps XML format for more information
+ * {@link https://www.sitemaps.org/protocol.html}
+ *
  * @param {object} opts - Sitemap options
- * @param {string} opts.hostname
- * @param {string} [opts.changefreq]
- * @param {string} [opts.lastmod]
- * @param {string} [opts.priority]
- * @param {string} [opts.filename]
- * @param {string} [opts.pattern]
+ * @param {string} opts.hostname - Parent URL for each entry
+ * @param {'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly'} [opts.changefreq] - Default change frequency for each entry
+ * @param {string} [opts.lastmod] - Default last modified date in ISO format
+ * @param {string} [opts.priority] - Default priority for each entry between 0-1
+ * @param {string} [opts.filename] - Sitemap filename, e.g. sitemap.xml
+ * @param {string | string[]} [opts.pattern] - Minimatch pattern
  * @returns {import('metalsmith').Plugin} Metalsmith plugin
  */
 const plugin = (opts) => {
-  opts = opts || {}
-
   if (!opts.hostname) {
     throw new Error('"hostname" is required')
   }

lib/get-macro-options/index.js

@@ -12,6 +12,9 @@ const marked = new DesignSystemMarked().use({
       /**
        * Render paragraphs without `<p>` wrappers
        * for macro options in `<td>` table cells
+       *
+       * @param {import('marked').Tokens.Paragraph} token - Paragraph token
+       * @returns {string} Rendered paragraph
        */
       renderer(token) {
         return this.parser.parseInline(token.tokens)
@@ -189,7 +192,9 @@ function getAdditionalComponentOptions(options, parent) {
  *   }
  * ```
  *
- * */
+ * @param {string} componentName - Component name
+ * @returns {{ name: string, id: string, options: unknown[] }} Macro options
+ */
 function getMacroOptions(componentName) {
   // The design system uses a different name for the input component.
   if (componentName === 'text-input') {

lib/marked/renderer.js

@@ -3,6 +3,7 @@
  * (for example, HTML code inside Markdown)
  *
  * @param {TokenCode} token - Marked code token
+ * @returns {string} Code block
  */
 exports.code = function (token) {
   if (!token.lang) {
@@ -18,12 +19,13 @@ exports.code = function (token) {
  * Render single images without `<p>` wrappers
  *
  * @param {TokenText | TokenParagraph} token - Marked paragraph token
+ * @returns {string | false} Rendered image or false
  */
 exports.image = function (token) {
   const { tokens } = token
 
   return tokens?.length === 1 && tokens[0].type === 'image'
-    ? this.parser.parseInline(tokens) + '\n'
+    ? `${this.parser.parseInline(tokens)}\n`
     : false // Fall back to default renderer
 }
 

lib/metalsmith-title-checker.js

@@ -1,8 +1,6 @@
 /**
  * Metalsmith plugin to check each page has a unique title.
  * Which is required to make sure users of assistive technologies can navigate easily.
- *
- * @return {Function}
  */
 
 function groupFilesByTitle(filenames, files) {
@@ -76,9 +74,9 @@ module.exports = function titleChecker() {
 
     if (filesWithoutTitles.length) {
       throw Error(
-        'The following file(s) do not have titles:\n\n' +
-          filesWithoutTitles.map((file) => `- ${file}`).join('\n') +
-          '\n'
+        `The following file(s) do not have titles:\n\n${filesWithoutTitles
+          .map((file) => `- ${file}`)
+          .join('\n')}\n`
       )
     }
     done()

lib/metalsmith.js

@@ -85,7 +85,7 @@ module.exports = metalsmith
   .use(extractPageHeadings())
 
   // ignore files from build
-  .ignore(['.DS_Store', '.eslintrc.js'])
+  .ignore(['.DS_Store', '.eslintrc.js', 'tsconfig.json'])
 
   // convert *.scss files to *.css
   .use(
@@ -137,6 +137,16 @@ module.exports = metalsmith
       copyAssets('{fonts,images}/*', {
         cwd: join(dirname(require.resolve('govuk-frontend')), 'assets'),
         dest: 'assets'
+      }),
+
+      copyAssets('manifest.json', {
+        cwd: join(dirname(require.resolve('govuk-frontend')), 'assets'),
+        dest: 'assets'
+      }),
+
+      copyAssets('govuk-frontend.min.css?(.map)', {
+        cwd: dirname(require.resolve('govuk-frontend')),
+        dest: 'stylesheets'
       })
     ])
 

lib/nunjucks/globals.js

@@ -14,6 +14,9 @@ nunjucks.configure(join(paths.views, 'layouts'))
 /**
  * This helper function takes a path of a *.md.njk file and
  * returns the Nunjucks syntax inside that file without markdown data and imports
+ *
+ * @param {string} path - Path to Nunjucks file
+ * @returns {string} Nunjucks code for the file
  */
 exports.getNunjucksCode = function (path) {
   const { content } = matter(readFileSync(path, 'utf-8'))
@@ -27,20 +30,26 @@ exports.getNunjucksCode = function (path) {
 /**
  * This helper function takes a path of a *.md.njk file and
  * returns the frontmatter as an object
+ *
+ * @param {string} path - Path to Nunjucks file
+ * @returns {{ [key: string]: unknown }} Frontmatter object
  */
 exports.getFrontmatter = function (path) {
   return matter(readFileSync(path, 'utf-8')).data
 }
 
 /**
  * Get 'fingerprinted' version of a given asset file
+ *
+ * @param {string} file - Relative path to asset
+ * @returns {string} Relative path to asset with added hash fingerprint
  */
 exports.getFingerprint = function (file) {
   file = normalize(file)
 
   // Skip fingerprints in development for Browsersync inject (without reload)
   if (process.env.NODE_ENV === 'development') {
-    return '/' + slash(file)
+    return `/${slash(file)}`
   }
 
   // Grab fingerprint array from the template context
@@ -65,23 +74,24 @@ exports.getFingerprint = function (file) {
   }
 
   // Look for a fingerprinted asset at this path relative to the site root
-  return '/' + slash(fingerprints[file].path)
+  return `/${slash(fingerprints[file].path)}`
 }
 
 /**
  * This helper function takes a path of a *.md.njk file and
  * returns the HTML rendered by Nunjucks without markdown data
+ *
+ * @param {string} path - Path to Nunjucks file
+ * @returns {string} HTML rendered by the file
  */
 exports.getHTMLCode = function (path) {
   const { content } = matter(readFileSync(path, 'utf-8'))
 
   let html = ''
   try {
     html = nunjucks.renderString(content).trim()
-  } catch (err) {
-    if (err) {
-      console.log('Could not get HTML code from ' + path)
-    }
+  } catch (error) {
+    console.log(`Could not get HTML code from ${path}`)
   }
 
   const options = beautify.html.defaultOptions()