Merge pull request #2446 from nhsuk/examples-code

Port Nunjucks syntax highlighting from GOV.UK Design System

Author: colinrotherham

CHANGELOG.md

@@ -1,5 +1,12 @@
 # NHS digital service manual Changelog
 
+## Unreleased
+
+:wrench: **Maintenance**
+
+- Port Nunjucks syntax highlighting from GOV.UK Design System
+- Support focus and keyboard left/right scrolling on code blocks
+
 ## 8.7.2 - 2 March 2026
 
 :wrench: **Maintenance**

app.js

@@ -136,8 +136,8 @@ env.addGlobal('getMacroOptions', macroOptions.getMacroOptions)
 env.addGlobal('getMacroPageName', macroOptions.getMacroPageName)
 env.addFilter('highlight', filters.highlight)
 env.addFilter('kebabCase', filters.kebabCase)
-env.addFilter('markdown', filters.markdown)
 env.addFilter('slugify', filters.slugify)
+env.addFilter('unindent', filters.unindent)
 
 // Render standalone design examples
 app.get('/design-example/:group/:item/:type', (req, res, next) => {

app/config.js

@@ -26,6 +26,7 @@ module.exports = {
   // Nunjucks search paths
   nunjucksPaths: [
     join(sourcePath, 'views'),
+    join(sourcePath, 'views/components'),
     join(modulePath, 'nhsuk-frontend/dist/nhsuk/components'),
     join(modulePath, 'nhsuk-frontend/dist/nhsuk/macros'),
     join(modulePath, 'nhsuk-frontend/dist/nhsuk'),

app/javascripts/code.jsdom.test.mjs

@@ -0,0 +1,48 @@
+import { mockResizeObserver } from 'jsdom-testing-mocks'
+import { createAll } from 'nhsuk-frontend'
+
+import { Code } from './code.mjs'
+
+const resizeObserverMock = mockResizeObserver()
+
+describe('NHS digital service manual code', () => {
+  /** @type {HTMLElement} */
+  let $container
+
+  beforeEach(() => {
+    document.body.innerHTML = `
+      <pre class="app-code" data-module="app-code">
+        <code class="app-code__container hljs"></code>
+      </pre>
+    `
+
+    const [code] = createAll(Code)
+    $container = code.$container
+
+    jest.spyOn($container, 'clientWidth', 'get').mockReturnValue(1024)
+    jest.spyOn($container, 'clientHeight', 'get').mockReturnValue(768)
+
+    jest.spyOn($container, 'scrollWidth', 'get').mockReturnValue(500)
+    jest.spyOn($container, 'scrollHeight', 'get').mockReturnValue(500)
+  })
+
+  describe('Keyboard focus', () => {
+    it('should not add tabindex by default', async () => {
+      expect($container).not.toHaveAttribute('tabindex')
+    })
+
+    it('should add tabindex by code overflows container', async () => {
+      jest.spyOn($container, 'clientWidth', 'get').mockReturnValue(320)
+      jest.spyOn($container, 'clientHeight', 'get').mockReturnValue(240)
+
+      resizeObserverMock.mockElementSize($container, {
+        contentBoxSize: { inlineSize: 500, blockSize: 500 }
+      })
+
+      // Trigger resize
+      resizeObserverMock.resize()
+
+      expect($container).toHaveAttribute('tabindex')
+    })
+  })
+})

app/javascripts/code.mjs

@@ -0,0 +1,62 @@
+import { Component, ElementError } from 'nhsuk-frontend'
+
+/**
+ * Code with scroll container component
+ *
+ * @augments {Component<HTMLPreElement>}
+ */
+export class Code extends Component {
+  static elementType = HTMLPreElement
+
+  /**
+   * @param {Element | null} $root - HTML element to use for component
+   */
+  constructor($root) {
+    super($root)
+
+    const $container = this.$root.querySelector('.app-code__container')
+    if (!($container instanceof HTMLElement)) {
+      throw new ElementError({
+        component: Code,
+        element: $container,
+        identifier: 'Code container (`.app-code__container`)'
+      })
+    }
+
+    this.$container = $container
+    this.handleEnableFocus = this.enableFocus.bind(this)
+
+    // ResizeObserver isn't supported by Safari < 13.1 so we need to fall back
+    // to window resize, checking the container width has actually changed
+    if ('ResizeObserver' in window) {
+      this.resizeObserver = new window.ResizeObserver(this.handleEnableFocus)
+      this.resizeObserver.observe(this.$container)
+    } else {
+      window.addEventListener('resize', this.handleEnableFocus)
+    }
+  }
+
+  /**
+   * Enable container focus
+   */
+  enableFocus() {
+    if (this.isOverflowing()) {
+      this.$container.setAttribute('tabindex', '0')
+    } else {
+      this.$container.removeAttribute('tabindex')
+    }
+  }
+
+  /**
+   * Checks if the container scrollable width or height is greater than the
+   * width or height the container is being rendered at
+   */
+  isOverflowing() {
+    return (
+      this.$container.scrollHeight > this.$container.clientHeight ||
+      this.$container.scrollWidth > this.$container.clientWidth
+    )
+  }
+
+  static moduleName = 'app-code'
+}

app/javascripts/main.jsdom.test.mjs

@@ -3,11 +3,6 @@ import { initAll } from 'nhsuk-frontend'
 jest.mock('nhsuk-frontend')
 
 describe('NHS digital service manual', () => {
-  beforeEach(() => {
-    document.documentElement.innerHTML = ''
-    document.body.classList.add('nhsuk-frontend-supported')
-  })
-
   describe('NHS.UK frontend', () => {
     it('should init all components', async () => {
       await import('./main.mjs')

app/javascripts/main.mjs

@@ -3,6 +3,7 @@ import { createAll, initAll } from 'nhsuk-frontend'
 
 // NHS digital service manual components
 import initAccessibleAutocomplete from './accessible-autocomplete.mjs'
+import { Code } from './code.mjs'
 import { DesignExample } from './design-example.mjs'
 import { inputValue, onConfirm, source, suggestion } from './search.mjs'
 
@@ -22,5 +23,8 @@ initAccessibleAutocomplete({
   }
 })
 
+// Code highlight blocks
+createAll(Code)
+
 // Design examples
 createAll(DesignExample)

app/stylesheets/app/_app-reading-width.scss

@@ -40,8 +40,7 @@
     .app-example,
     .nhsuk-table,
     .app-colour-list,
-    .app-example--image,
-    .app-pre {
+    .app-example--image {
       max-width: 44em;
     }
 

app/stylesheets/app/_code-block.scss

@@ -2,29 +2,13 @@
 
 @use "../vendor/nhsuk-frontend" as *;
 
-/// Code showing deleted and inserted lines:
-
-code del {
-  background-color: nhsuk-tint(nhsuk-colour("red"), 85%);
-  color: nhsuk-shade(nhsuk-colour("red"), 10%);
-  text-decoration: none;
-}
-
-code ins {
-  background-color: nhsuk-tint(nhsuk-colour("green"), 85%);
-  color: nhsuk-shade(nhsuk-colour("green"), 8%);
-  text-decoration: none;
-}
-
 ////
 /// Code block highlighting
 ////
 
-code[class*="language-"],
-pre[class*="language-"] {
+code[class*="language-"] {
   color: #000000;
   background: none;
-  overflow: auto;
   text-align: left;
   white-space: pre;
   word-spacing: normal;
@@ -41,116 +25,30 @@ pre[class*="language-"] {
   hyphens: none;
 }
 
-pre[class*="language-"]::-moz-selection,
-pre[class*="language-"] ::-moz-selection,
 code[class*="language-"]::-moz-selection,
 code[class*="language-"] ::-moz-selection {
   text-shadow: none;
   background: #b3d4fc;
 }
 
-pre[class*="language-"]::selection,
-pre[class*="language-"] ::selection,
 code[class*="language-"]::selection,
 code[class*="language-"] ::selection {
   text-shadow: none;
   background: #b3d4fc;
 }
 
 @media print {
-  code[class*="language-"],
-  pre[class*="language-"] {
+  code[class*="language-"] {
     text-shadow: none;
   }
 }
 
-pre[class*="language-"] {
-  padding: 1em;
-  overflow: auto;
-
-  @include nhsuk-responsive-margin(4, "bottom");
-}
-
 pre code[class*="language-"] {
   display: block;
-  background: #ffffff;
 }
 
 :not(pre) > code[class*="language-"] {
   padding: 0.1em;
   border-radius: 0.3em;
   white-space: normal;
 }
-
-.token.comment,
-.token.prolog,
-.token.doctype,
-.token.cdata {
-  color: #708090;
-}
-
-.token.punctuation {
-  color: #999999;
-}
-
-.namespace {
-  opacity: 0.7;
-}
-
-.token.property,
-.token.tag,
-.token.boolean,
-.token.number,
-.token.constant,
-.token.symbol,
-.token.deleted {
-  color: #990055;
-}
-
-.token.selector,
-.token.attr-name,
-.token.string,
-.token.char,
-.token.builtin,
-.token.inserted {
-  color: #669900;
-}
-
-.token.operator,
-.token.entity,
-.token.url,
-.language-css .token.string,
-.style .token.string {
-  color: #9a6e3a;
-  background: hsla(0deg, 0%, 100%, 0.5);
-}
-
-.token.atrule,
-.token.attr-value,
-.token.keyword {
-  color: #0077aa;
-}
-
-.token.function,
-.token.class-name {
-  color: #dd4a68;
-}
-
-.token.regex,
-.token.important,
-.token.variable {
-  color: #ee9900;
-}
-
-.token.important,
-.token.bold {
-  font-weight: bold;
-}
-
-.token.italic {
-  font-style: italic;
-}
-
-.token.entity {
-  cursor: help;
-}

app/stylesheets/app/_code-highlight.scss

@@ -25,13 +25,17 @@ p code {
 }
 
 // Highlight code in a block
-.app-pre {
+.app-code,
+.app-code__container {
+  font-family: $app-code-font;
+}
+
+.app-code {
   background: nhsuk-colour("white");
   border: 1px solid $nhsuk-border-colour;
-  margin-top: 0;
-  overflow: auto;
-  padding: nhsuk-spacing(3);
+  margin: 0;
   position: relative;
+  font-size: inherit;
 
   @include nhsuk-responsive-margin(4, "bottom");
 
@@ -44,29 +48,14 @@ p code {
   }
 }
 
-.hljs {
-  background-color: nhsuk-colour("white");
-  color: nhsuk-colour("black");
-  display: block;
-  overflow-x: scroll;
-  padding: 0;
-}
-
-.hljs.css .hljs-selector-class,
-.hljs.css .hljs-selector-tag,
-.hljs.css .hljs-keyword {
-  color: nhsuk-colour("purple");
-}
-
-.app-tabs__container pre {
-  -ms-flex-item-align: stretch;
-  -ms-grid-row-align: stretch;
-  align-self: stretch;
-  background-color: nhsuk-colour("white");
-  padding: 0;
-}
+.app-code__container {
+  padding: nhsuk-spacing(3);
+  overflow-x: auto;
+  line-height: 1.5;
+  border: $nhsuk-focus-width solid transparent;
 
-.app-tabs__container pre,
-.app-tabs__container code {
-  font-family: $app-code-font;
+  &:focus {
+    border: $nhsuk-focus-width solid $nhsuk-focus-text-colour;
+    outline: $nhsuk-focus-width solid $nhsuk-focus-colour;
+  }
 }