@defra/docusaurus-theme-govuk 0.0.13-alpha → 0.0.15-alpha

package/index.js

@@ -8,6 +8,34 @@ const removeMarkdown = require('remove-markdown');
 // handles deduplication automatically (second "Options" → "options-1", etc.).
 const GithubSlugger = require('github-slugger');
 
+// Remark plugin: converts `<!-- no-sidebar -->` inline HTML comments inside
+// headings into a `data-no-sidebar` HTML attribute (via mdast hProperties) so
+// the runtime DOM scanner can detect and skip them. MDX/remark-rehype drops
+// raw HTML comment nodes before they reach the browser DOM, so a compile-time
+// transformation is the only reliable way to carry this signal through.
+function remarkNoSidebar() {
+  return function (tree) {
+    if (!tree || !Array.isArray(tree.children)) return;
+    for (const node of tree.children) {
+      if (node.type !== 'heading') continue;
+      const children = node.children || [];
+      const commentIdx = children.findIndex(
+        child => child.type === 'html' && child.value?.includes('no-sidebar')
+      );
+      if (commentIdx === -1) continue;
+      // Strip the comment node from the heading children
+      node.children = children.filter((_, i) => i !== commentIdx);
+      // Trim trailing whitespace in the preceding text node, if any
+      const prev = node.children[commentIdx - 1];
+      if (prev?.type === 'text') prev.value = prev.value.trimEnd();
+      // Attach hProperties so remark-rehype passes data-no-sidebar to the element
+      node.data = node.data || {};
+      node.data.hProperties = node.data.hProperties || {};
+      node.data.hProperties['data-no-sidebar'] = 'true';
+    }
+  };
+}
+
 // Parse markdown content and build a sidebar config from h2/h3 headings.
 // h2 → top-level items; h3 → nested items under the preceding h2.
 // Items include both the display text and an anchor href (basePath + '#' + anchor).
@@ -32,8 +60,8 @@ function parseHeadingsToSidebar(content, basePath) {
   let currentH2 = null;
 
   for (const line of lines) {
-    const h2 = line.match(/^## (.+)$/);
-    const h3 = line.match(/^### (.+)$/);
+    const h2 = !line.includes('<!-- no-sidebar -->') && line.match(/^## (.+)$/);
+    const h3 = !line.includes('<!-- no-sidebar -->') && line.match(/^### (.+)$/);
 
     if (h2) {
       const raw = h2[1].trim();
@@ -53,6 +81,40 @@ function parseHeadingsToSidebar(content, basePath) {
   return items.map(({ _anchor, ...item }) => item);
 }
 
+// Mutate the webpack config to inject remarkNoSidebar into the MDX loader.
+// Extracted to keep configureWebpack's cognitive complexity within limits.
+function injectNoSidebarPlugin(config) {
+  try {
+    injectIntoRules(config.module?.rules || []);
+  } catch (e) {
+    // Non-fatal: the build-time parseHeadingsToSidebar still handles static sidebars.
+    console.warn('[docusaurus-theme-govuk] Could not inject no-sidebar remark plugin:', e.message);
+  }
+}
+
+function normaliseUses(use) {
+  if (Array.isArray(use)) return use;
+  return use ? [use] : [];
+}
+
+function injectIntoUses(uses) {
+  for (const use of uses) {
+    if (typeof use?.loader === 'string' && use.loader.includes('mdx-loader')) {
+      use.options = use.options || {};
+      use.options.beforeDefaultRemarkPlugins = use.options.beforeDefaultRemarkPlugins || [];
+      use.options.beforeDefaultRemarkPlugins.push(remarkNoSidebar);
+    }
+  }
+}
+
+function injectIntoRules(rules) {
+  for (const rule of rules) {
+    if (!rule || typeof rule !== 'object') continue;
+    if (Array.isArray(rule.oneOf)) injectIntoRules(rule.oneOf);
+    injectIntoUses(normaliseUses(rule.use));
+  }
+}
+
 module.exports = function themeGovuk(context, options) {
   const siteDir = context.siteDir;
 
@@ -144,6 +206,13 @@ module.exports = function themeGovuk(context, options) {
     },
 
     configureWebpack(config, isServer, utils) {
+      // Inject our no-sidebar remark plugin into the MDX loader so that
+      // `<!-- no-sidebar -->` comments in headings are converted to
+      // data-no-sidebar attributes before the DOM is rendered. We mutate the
+      // existing config directly since webpack-merge cannot deep-merge loader
+      // options arrays correctly.
+      injectNoSidebarPlugin(config);
+
       // Helper: resolve a package from the consumer's siteDir.
       // Uses require.resolve with paths so it follows Node's resolution
       // (handles hoisted AND nested node_modules like @docusaurus/core/node_modules/react-router-dom).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/docusaurus-theme-govuk",
-  "version": "0.0.13-alpha",
+  "version": "0.0.15-alpha",
   "description": "A Docusaurus theme implementing the GOV.UK Design System for consistent, accessible documentation sites",
   "main": "index.js",
   "license": "MIT",

package/src/css/components.scss

@@ -9,9 +9,6 @@
 
 .app-layout-sidebar__nav {
   width: 250px;
-  // Padding-left gives room for the nav's active indicator (margin-left: -14px)
-  // which would otherwise be clipped by the overflow-y containment.
-  padding-left: 15px;
   flex-shrink: 0;
   position: sticky;
   top: 1rem;
@@ -20,6 +17,16 @@
   // Always reserve the scrollbar gutter so expanding subnav items don't
   // cause a horizontal layout shift when the scrollbar appears.
   scrollbar-gutter: stable;
+
+  // Remove side bar top border
+  padding-top: 0;
+  border: 0;
+
+  @media (min-width: 48.125em) {
+    overflow: auto !important;
+    margin-left: -16px;
+    padding-left: 16px;
+  }
 }
 
 .app-layout-sidebar__content {
@@ -84,6 +91,126 @@
   }
 }
 
+// Navigation menu mobile styling
+.app-layout-sidebar__nav .not-govuk-navigation-menu__list > .not-govuk-navigation-menu__list__item {
+  border-bottom: 1px solid #cecece;
+
+  position: relative;
+  padding-top: 5px;
+  padding-bottom: 5px;
+  margin-bottom: 5px;
+  font-size: 1rem;
+  padding-left: 0;
+  margin-left: 0;
+  
+  @media (min-width: 48.125em) {
+    border-bottom: 0;
+
+    &:after {
+      border-bottom: 0;
+    }
+  }
+
+  .not-govuk-navigation-menu__list__link {
+    display: flex;
+    padding: 2px 0;
+  }
+
+  &--active {
+    border-left: none;
+
+    @media (min-width: 48.125em) {
+      border-left: 4px solid #1d70b8;
+      padding-left: 11px;
+      margin-left: -15px;
+      border-bottom: 0;
+      font-weight: bold;
+    }
+  }
+}
+
+// Active indicator on sub-items.
+
+.app-layout-sidebar__nav .not-govuk-navigation-menu__list__subitems {
+
+  .not-govuk-navigation-menu__list__item {
+    padding: 5px 0 5px 15px;
+    margin-bottom: 5px;
+    border-left-width: 0px;
+    border-left-style: solid;
+  }
+
+  .not-govuk-navigation-menu__list__item--active {
+    border-left: none;
+
+    @media (min-width: 48.125em) {
+      border-left: 4px solid #1d70b8;
+      padding-left: 10px;
+      font-weight: bold;
+
+      .not-govuk-navigation-menu__list__link {
+        font-weight: bold;
+      }
+    }
+  }
+
+  // Remove the '— ' dash from all sub-items.
+  .not-govuk-navigation-menu__list__item::before {
+    content: none;
+  }
+
+  padding-left: 0;
+}
+
+// Sidebar nav section headings and mobile toggle
+// Desktop: headings are non-link spans, visually distinct from link items
+.not-govuk-navigation-menu__list__heading {
+  display: block;
+  padding: 2px 0;
+  color: #0b0c0c;
+  font-weight: bold;
+  cursor: default;
+}
+
+// Mobile: headings become toggle buttons
+.not-govuk-navigation-menu__list__heading-toggle {
+  display: inline-flex;
+  align-items: center;
+  padding: 2px 0;
+  background: none;
+  border: none;
+  text-align: left;
+  font-family: inherit;
+  font-size: inherit;
+  font-weight: bold;
+  color: #1d70b8;
+  cursor: pointer;
+
+  // Chevron indicator on the right, pointing down (collapsed)
+  &::after {
+    content: '';
+    display: inline-block;
+    width: 0;
+    height: 0;
+    border-left: 4px solid transparent;
+    border-right: 4px solid transparent;
+    border-top: 5px solid currentColor;
+    flex-shrink: 0;
+    margin-left: 8px;
+  }
+
+  &[aria-expanded="true"]::after {
+    transform: rotate(180deg);
+  }
+
+  &:focus {
+    outline: 3px solid transparent;
+    color: #0b0c0c;
+    background-color: #fd0;
+    box-shadow: 0 -2px #fd0, 0 4px #0b0c0c;
+  }
+}
+
 // Pagination
 .app-pagination__container {
   display: flex;
@@ -172,6 +299,16 @@
   flex-wrap: nowrap;
 }
 
+.govuk-header__link--homepage:focus svg g {
+  fill: #0b0c0c !important;
+}
+
+// Mirror GDS Design System
+.govuk-header__logotype-text {
+  font-size: 1.5rem;
+  line-height: 1.25;
+}
+
 .app-header-search {
   margin-left: auto;
   flex-shrink: 0;
@@ -185,29 +322,36 @@
     width: 300px;
   }
 
-  // Input field — always white background with search icon on the left
+  // Input field — white background, GOV.UK dark border, search icon on the left
   .autocomplete__input {
     width: 100%;
-    padding: 4px 8px 4px 40px;
-    border: 2px solid #fff;
+    // GOV.UK inputs use 5px vertical padding; left padding reserves space for
+    // the search icon, right padding keeps text clear of the autocomplete clear button
+    padding: 5px 8px 5px 36px;
+    // Dark border matches govuk-input — visible on white and meets contrast requirements
+    border: 2px solid transparent;
     border-radius: 0;
     background-color: #fff;
     background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%230b0c0c' stroke-width='2.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='11' cy='11' r='8'/%3E%3Cline x1='21' y1='21' x2='16.65' y2='16.65'/%3E%3C/svg%3E");
     background-repeat: no-repeat;
-    background-position: 10px center;
-    background-size: 20px 20px;
+    background-position: 8px center;
+    background-size: 18px 18px;
     color: #0b0c0c;
     font-family: Helvetica, Arial, sans-serif;
-    font-size: 0.875rem;
     box-sizing: border-box;
+    // Prevent browser-native search-cancel button (replaced by autocomplete's own)
+    appearance: none;
 
     &::placeholder {
       color: #505a5f;
     }
 
+    // GOV.UK focus style: yellow outline with dark inner border
     &:focus {
       outline: 3px solid #fd0;
       outline-offset: 0;
+      box-shadow: inset 0 0 0 2px #0b0c0c;
+      border-color:#0b0c0c;
     }
   }
 
@@ -218,7 +362,6 @@
     left: 0;
     right: 0;
     background: #fff;
-    border: 2px solid #0b0c0c;
     border-radius: 0;
     margin: 0;
     padding: 0;
@@ -233,10 +376,13 @@
     position: relative;
   }
 
+  .autocomplete__menu--overlay {
+    box-shadow: rgba(11, 12, 12, .256863) 0 5px 5px;
+  }
+
   .autocomplete__option {
     padding: 8px 12px;
     font-family: Helvetica, Arial, sans-serif;
-    font-size: 0.875rem;
     color: #0b0c0c;
     cursor: pointer;
     border-bottom: 1px solid #f3f2f1;
@@ -264,7 +410,6 @@
 
   .app-search__context {
     display: block;
-    font-size: 0.75rem;
     color: #505a5f;
     margin-top: 2px;
   }
@@ -272,7 +417,6 @@
   .autocomplete__option--no-results {
     padding: 8px 12px;
     font-family: Helvetica, Arial, sans-serif;
-    font-size: 0.875rem;
     color: #505a5f;
   }
 
@@ -290,7 +434,23 @@
   }
 }
 
-@media (max-width: 767px) {
+@media (max-width: 769px) {
+  .govuk-header__container {
+    flex-direction: column;
+    align-items: flex-start;
+  }
+
+  .app-header-search {
+    margin-left: 0;
+    margin-bottom: 10px;
+    width: 100%;
+  }
+
+  .app-header-search div[role="search"],
+  .app-header-search .autocomplete__wrapper {
+    width: 100%;
+  }
+
   .app-layout-sidebar {
     flex-direction: column;
     gap: 0;
@@ -310,9 +470,4 @@
     width: 100%;
     min-width: 0;
   }
-
-  .app-header-search .autocomplete__wrapper {
-    width: 180px;
-  }
-}
-
+}

package/src/css/prose-scope.scss

@@ -4,54 +4,54 @@
 
 .app-prose-scope {
   // Headings
-  h1 {
+  h1:not(.app-no-prose *) {
     @extend %govuk-heading-xl;
   }
 
-  h2 {
+  h2:not(.app-no-prose *) {
     @extend %govuk-heading-l;
   }
 
-  h3 {
+  h3:not(.app-no-prose *) {
     @extend %govuk-heading-m;
   }
 
-  h4 {
+  h4:not(.app-no-prose *) {
     @extend %govuk-heading-s;
   }
 
   // Body text
-  p {
+  p:not(.app-no-prose *) {
     @extend %govuk-body-m;
   }
 
   // Bold text
-  strong,
-  b {
+  strong:not(.app-no-prose *),
+  b:not(.app-no-prose *) {
     font-weight: 700;
   }
 
   // Lists
-  ul,
-  ol {
+  ul:not(.app-no-prose *),
+  ol:not(.app-no-prose *) {
     @extend %govuk-list;
   }
 
-  ol {
+  ol:not(.app-no-prose *) {
     @extend %govuk-list--number;
   }
 
-  ul {
+  ul:not(.app-no-prose *) {
     @extend %govuk-list--bullet;
   }
 
   // Links
-  a {
+  a:not(.app-no-prose *) {
     @extend %govuk-link;
   }
 
   // Section breaks
-  hr {
+  hr:not(.app-no-prose *) {
     @extend %govuk-section-break;
     @extend %govuk-section-break--visible;
     @extend %govuk-section-break--xl;

package/src/css/theme.scss

@@ -7,6 +7,9 @@
 /* Import component styles */
 @import './components.scss';
 
+/* GOV.UK grid system */
+@import 'govuk-frontend/dist/govuk/objects/grid';
+
 /*
  * Set the default font on the body so that ALL elements
  * (header, footer, service-nav, etc.) inherit the same stack.
@@ -23,13 +26,20 @@ body {
  * and our layout, breaking GOV.UK Frontend's flex sticky-footer chain.
  * Rather than patching the chain, own the full-height context here.
  */
-.govuk-template--rebranded {
+.govuk-template__body-inner {
+  background-color: #ffffff;
   display: flex;
   flex-direction: column;
   min-height: 100vh;
 }
 
-.govuk-template--rebranded > .govuk-width-container {
+.govuk-template__body-inner > .govuk-width-container {
   flex: 1 0 auto;
-  width: 100%;
+  width: calc(100% - 30px);
+}
+
+@media (min-width: 40.0625em) {
+  .govuk-template__body-inner > .govuk-width-container {
+    width: calc(100% - 60px);
+  }
 }

package/src/theme/Layout/index.js

@@ -98,6 +98,41 @@ function getActiveSection(pathname, navigation) {
   });
 }
 
+/**
+ * Initialise the govuk-frontend ServiceNavigation JS for the mobile menu toggle.
+ * The @not-govuk React component renders the toggle button with `hidden` by default
+ * (progressive enhancement); this hook removes `hidden` on mobile and wires up the
+ * click handler exactly as govuk-frontend expects.
+ */
+function useServiceNavigationToggle() {
+  useEffect(() => {
+    let cancelled = false;
+    import('govuk-frontend').then(({ ServiceNavigation }) => {
+      if (cancelled) return;
+      // govuk-frontend checks for this class before initialising any component.
+      // Normally added by an inline <script> snippet in the HTML template; we
+      // add it here since Docusaurus doesn't use that template pattern.
+      document.body.classList.add('govuk-frontend-supported');
+      document.querySelectorAll('[data-module="govuk-service_navigation"]').forEach((el) => {
+        try {
+          const instance = new ServiceNavigation(el);
+          el._govukServiceNav = instance;
+        } catch (e) {
+          // May fail if the CSS custom property --govuk-breakpoint-tablet isn't set.
+          // Fall back to injecting it directly so the toggle still works.
+          if (e.message?.includes('CSS custom property')) {
+            document.documentElement.style.setProperty('--govuk-breakpoint-tablet', '40.0625em');
+            el._govukServiceNav = new ServiceNavigation(el);
+          } else {
+            throw e;
+          }
+        }
+      });
+    });
+    return () => { cancelled = true; };
+  }, []);
+}
+
 export default function Layout(props) {
   const location = useLocation();
   const {siteConfig} = useDocusaurusContext();
@@ -109,6 +144,8 @@ export default function Layout(props) {
     noFooter,
   } = props;
 
+  useServiceNavigationToggle();
+
   const navigation = govukConfig.navigation || [];
   const header = govukConfig.header || {};
   const phaseBanner = govukConfig.phaseBanner;
@@ -170,6 +207,10 @@ export default function Layout(props) {
     for (const el of headings) {
       const id = el.id;
       if (!id) continue;
+      // Skip headings marked with <!-- no-sidebar --> in the source.
+      // The remarkNoSidebar plugin (index.js) converts the comment to a
+      // data-no-sidebar attribute at compile time so it survives MDX rendering.
+      if (el.dataset?.noSidebar) continue;
       const text = el.textContent?.trim() ?? '';
       const href = withBase(`${pathname}#${id}`);
       if (el.tagName === 'H2') {
@@ -196,14 +237,14 @@ export default function Layout(props) {
   return (
     <LayoutProvider>
       <Head>
-        <html lang="en-GB" className="govuk-template" />
-        <body className="govuk-template__body" />
+        <html lang="en-GB" className="govuk-template govuk-template--rebranded" />
+        <body className={isHomepage ? 'govuk-template__body app-homepage' : 'govuk-template__body'} />
         <meta name="theme-color" content="#0b0c0c" />
         {title && <title>{title}</title>}
         {description && <meta name="description" content={description} />}
       </Head>
 
-      <div className="govuk-template--rebranded">
+      <div className="govuk-template__body-inner">
         <AnnouncementBar />
 
         {/* Hidden navbar element for Docusaurus hooks */}
@@ -266,8 +307,8 @@ export default function Layout(props) {
           </div>
         )}
 
-        <div className="govuk-width-container">
-          {phaseBanner && (
+        {phaseBanner && (
+          <div className="govuk-width-container">
             <PhaseBanner phase={phaseBanner.phase}>
               {phaseBanner.text}{' '}
               {phaseBanner.feedbackHref && (
@@ -276,10 +317,12 @@ export default function Layout(props) {
                 </a>
               )}
             </PhaseBanner>
-          )}
+          </div>
+        )}
 
-          <main id="main-content" className="govuk-main-wrapper">
-            {sidebarItems ? (
+        <main id="main-content" className={isHomepage ? undefined : 'govuk-main-wrapper'}>
+          {sidebarItems ? (
+            <div className="govuk-width-container">
               <div className="app-layout-sidebar">
                 <aside className="app-layout-sidebar__nav">
                   <SidebarNav items={sidebarItems} />
@@ -288,11 +331,15 @@ export default function Layout(props) {
                   {children}
                 </div>
               </div>
-            ) : (
-              children
-            )}
-          </main>
-        </div>
+            </div>
+          ) : isHomepage ? (
+            children
+          ) : (
+            <div className="govuk-width-container">
+              {children}
+            </div>
+          )}
+        </main>
 
         {!noFooter && (
           <Footer rebrand meta={footer.meta} />

package/src/theme/SearchBar/index.js

@@ -170,29 +170,34 @@ function SearchBarInner() {
   const Autocomplete = require('accessible-autocomplete/react').default;
 
   return (
-    <Autocomplete
-      id="govuk-search"
-      source={source}
-      templates={{
-        inputValue: (result) => (result ? result._label : ''),
-        suggestion: (result) => {
-          if (!result) return '';
-          const title = escapeHtml(result._label);
-          const context = result._context
-            ? `<span class="app-search__context">${escapeHtml(result._context)}</span>`
-            : '';
-          return `<span class="app-search__title">${title}</span>${context}`;
-        },
-      }}
-      displayMenu="overlay"
-      minLength={2}
-      placeholder="Search"
-      onConfirm={onConfirm}
-      tNoResults={() => 'No results found'}
-      tAssistiveHint={() =>
-        'When autocomplete results are available use up and down arrows to review and enter to select.'
-      }
-    />
+    <div role="search">
+      <label htmlFor="govuk-search" className="govuk-visually-hidden">
+        Search
+      </label>
+      <Autocomplete
+        id="govuk-search"
+        source={source}
+        templates={{
+          inputValue: (result) => (result ? result._label : ''),
+          suggestion: (result) => {
+            if (!result) return '';
+            const title = escapeHtml(result._label);
+            const context = result._context
+              ? `<span class="app-search__context">${escapeHtml(result._context)}</span>`
+              : '';
+            return `<span class="app-search__title">${title}</span>${context}`;
+          },
+        }}
+        displayMenu="overlay"
+        minLength={2}
+        placeholder="Search"
+        onConfirm={onConfirm}
+        tNoResults={() => 'No results found'}
+        tAssistiveHint={() =>
+          'When autocomplete results are available use up and down arrows to review and enter to select.'
+        }
+      />
+    </div>
   );
 }
 

package/src/theme/SidebarNav/index.js

@@ -4,30 +4,36 @@ import { useLocation } from '@docusaurus/router';
 /**
  * Hash- and pathname-aware sidebar navigation.
  *
- * Works for both anchor-based (auto-generated) and page-based (manual) sidebars.
+ * Desktop (≥770px): section headings are non-interactive spans; all groups
+ * are permanently expanded; active items get a left-border marker.
  *
- * SSR / no-JS: all groups are rendered expanded so content is accessible.
- * CSR after hydration:
- *   - Anchor hrefs (e.g. /api#constructor): active when pathname AND hash both match
- *   - Page hrefs (e.g. /building-a-plugin): active when pathname matches
- *   - Groups expand when the group itself or any child is active
+ * Mobile (<770px): section headings become toggle buttons; groups collapse
+ * and expand. Active groups start expanded. Active marker is hidden.
  *
- * State sentinel:
- *   null = not yet hydrated → expand all groups (SSR safe)
- *   str  = JS loaded (empty string means no hash present)
+ * SSR / no-JS: renders in desktop mode (all groups expanded).
  */
 export default function SidebarNav({ items }) {
   const [hash, setHash] = useState(null);
+  // null = not yet hydrated; false = desktop; true = mobile
+  const [isMobile, setIsMobile] = useState(null);
+  const [openGroups, setOpenGroups] = useState(new Set());
   const location = useLocation();
 
   useEffect(() => {
-    const update = () => setHash(window.location.hash.slice(1));
+    const update = () => setHash(globalThis.location.hash.slice(1));
     update();
-    window.addEventListener('hashchange', update);
-    return () => window.removeEventListener('hashchange', update);
+    globalThis.addEventListener('hashchange', update);
+    return () => globalThis.removeEventListener('hashchange', update);
+  }, []);
+
+  useEffect(() => {
+    const mql = globalThis.matchMedia('(max-width: 769px)');
+    const update = () => setIsMobile(mql.matches);
+    update();
+    mql.addEventListener('change', update);
+    return () => mql.removeEventListener('change', update);
   }, []);
 
-  // Split an href into its path and anchor components.
   function parseHref(href) {
     if (!href) return { path: '', anchor: '' };
     const idx = href.indexOf('#');
@@ -35,9 +41,6 @@ export default function SidebarNav({ items }) {
     return { path: href.slice(0, idx) || '/', anchor: href.slice(idx + 1) };
   }
 
-  // Return true if the given href matches the current browser location.
-  //   Anchor hrefs: both pathname and hash must match.
-  //   Page hrefs:   pathname match is sufficient (exact or child path).
   function isActive(href) {
     const { path, anchor } = parseHref(href);
     if (anchor) {
@@ -49,44 +52,75 @@ export default function SidebarNav({ items }) {
     );
   }
 
+  // When switching to mobile, open any groups that contain the active page.
+  useEffect(() => {
+    if (!isMobile || hash === null) return;
+    const active = new Set();
+    (items || []).forEach((item, i) => {
+      if (!Array.isArray(item.items) || !item.items.length) return;
+      if (isActive(item.href) || item.items.some(sub => isActive(sub.href))) {
+        active.add(i);
+      }
+    });
+    setOpenGroups(active);
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isMobile, location.pathname, hash]);
+
+  function toggleGroup(i) {
+    setOpenGroups(prev => {
+      const next = new Set(prev);
+      if (next.has(i)) next.delete(i);
+      else next.add(i);
+      return next;
+    });
+  }
+
   const cls = 'not-govuk-navigation-menu';
   const lCls = `${cls}__list`;
+  const itemCls = `${lCls}__item`;
+  const activeCls = `${itemCls}--active`;
+
+  function renderHeading(item, i, sublistId) {
+    if (isMobile) {
+      return (
+        <button
+          type="button"
+          className={`${lCls}__heading-toggle`}
+          aria-expanded={openGroups.has(i)}
+          aria-controls={sublistId}
+          onClick={() => toggleGroup(i)}
+        >
+          {item.text}
+        </button>
+      );
+    }
+    return <span className={`${lCls}__heading`}>{item.text}</span>;
+  }
 
   return (
     <nav className={cls}>
       <ul className={lCls}>
-        {items.map((item, i) => {
+        {(items || []).map((item, i) => {
           const hasChildren = Array.isArray(item.items) && item.items.length > 0;
-
-          // Pre-hydration (hash === null): expand everything so content is
-          // accessible without JS. After hydration: expand only if this group
-          // or one of its children is the active location.
-          const expanded =
-            hasChildren &&
-            (hash === null || isActive(item.href) || item.items.some(sub => isActive(sub.href)));
-
           const active = hash !== null && isActive(item.href);
+          const showChildren =
+            hasChildren && (isMobile === null || !isMobile || openGroups.has(i));
+          const liCls = active && !hasChildren ? `${itemCls} ${activeCls}` : itemCls;
+          const sublistId = hasChildren ? `sidebar-group-${i}` : undefined;
 
           return (
-            <li
-              key={i}
-              className={`${lCls}__item${active ? ` ${lCls}__item--active` : ''}`}
-            >
-              <a href={item.href} className={`${lCls}__link`}>
-                {item.text}
-              </a>
-              {expanded && (
-                <ul className={`${lCls}__subitems`}>
-                  {item.items.map((sub, j) => {
+            <li key={item.href || item.text} className={liCls}>
+              {hasChildren ? renderHeading(item, i, sublistId) : (
+                <a href={item.href} className={`${lCls}__link`}>{item.text}</a>
+              )}
+              {showChildren && (
+                <ul id={sublistId} className={`${lCls}__subitems`}>
+                  {item.items.map((sub) => {
                     const subActive = hash !== null && isActive(sub.href);
+                    const subCls = subActive ? `${itemCls} ${activeCls}` : itemCls;
                     return (
-                      <li
-                        key={j}
-                        className={`${lCls}__item${subActive ? ` ${lCls}__item--active` : ''}`}
-                      >
-                        <a href={sub.href} className={`${lCls}__link`}>
-                          {sub.text}
-                        </a>
+                      <li key={sub.href || sub.text} className={subCls}>
+                        <a href={sub.href} className={`${lCls}__link`}>{sub.text}</a>
                       </li>
                     );
                   })}
@@ -99,4 +133,3 @@ export default function SidebarNav({ items }) {
     </nav>
   );
 }
-