@defra/docusaurus-theme-govuk 0.0.1-alpha

package/src/lib/react-foundry-router-shim.js

@@ -0,0 +1,68 @@
+// Shim for @react-foundry/router that bridges React Router v5 (Docusaurus) to
+// the v6-style API that @react-foundry/router expects.
+//
+// This is needed because @react-foundry/router re-exports `Link` and
+// `useNavigate` from react-router v6, but Docusaurus ships react-router v5.
+// The shim maps v5 equivalents (useHistory, Link from react-router-dom) and
+// wires up useIsActive with the real location so @not-govuk components like
+// ServiceNavigation can correctly detect the active page.
+
+import { useLocation as _useLocation, useParams, Link } from 'react-router-dom';
+import { URI } from '@react-foundry/uri';
+
+export { useParams, Link };
+
+export const needSuspense = false;
+
+// Enhance location with parsed query string (matches @react-foundry/router API)
+const enhanceLocation = (location) => {
+  const search = location.search || '';
+  const params = new URLSearchParams(search);
+  const query = {};
+  for (const [key, value] of params.entries()) {
+    query[key] = value;
+  }
+  return { ...location, query };
+};
+
+export const useLocation = () => enhanceLocation(_useLocation());
+
+// Build useIsActive from the real location (mirrors @react-foundry/router/is-active)
+const includes = (haystack, needle) => {
+  const subIncludes = (h, n) =>
+    Array.isArray(n)
+      ? n.length === h.length && n.every((v, i) => subIncludes(h[i], v))
+      : typeof n === 'object'
+        ? typeof h === 'object' && Object.keys(n).every((k) => subIncludes(h[k], n[k]))
+        : n === h;
+  return subIncludes(haystack, needle);
+};
+
+export const useIsActive = () => {
+  const location = useLocation();
+
+  return (href, exact = true) => {
+    const target = URI.parse(href, location.pathname);
+    const dir = target.pathname.endsWith('/') ? target.pathname : target.pathname + '/';
+    // Root path '/' should only match exactly, not as a prefix for all paths
+    const pathStart = target.pathname === '' || (target.pathname !== '/' && location.pathname.startsWith(dir));
+    const pathMatch = target.pathname === '' || location.pathname === target.pathname;
+    const queryMatch = includes(location.query, target.query);
+    const activeExact = !!(pathMatch && queryMatch);
+    return exact ? activeExact : !!(activeExact || (pathStart && queryMatch));
+  };
+};
+
+// React Router v5 has useHistory, not useNavigate — wrap it
+export const useNavigate = () => {
+  const { useHistory } = require('react-router-dom');
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  const history = useHistory();
+  return (to) => {
+    if (typeof to === 'number') {
+      history.go(to);
+    } else {
+      history.push(to);
+    }
+  };
+};

package/src/theme/Admonition/index.js

@@ -0,0 +1,33 @@
+import React from 'react';
+import {InsetText, WarningText} from '@not-govuk/simple-components';
+
+const admonitionTitles = {
+  note: 'Note',
+  tip: 'Tip',
+  info: 'Info',
+  warning: 'Warning',
+  danger: 'Danger',
+  caution: 'Caution',
+};
+
+export default function Admonition({type = 'note', title, children}) {
+  const displayTitle = title || admonitionTitles[type] || 'Note';
+
+  // Warning and danger types use GOV.UK WarningText
+  if (type === 'warning' || type === 'danger' || type === 'caution') {
+    return (
+      <WarningText>
+        <strong>{displayTitle}: </strong>
+        {children}
+      </WarningText>
+    );
+  }
+
+  // All other types use GOV.UK InsetText
+  return (
+    <InsetText>
+      {title && <strong>{displayTitle}: </strong>}
+      {children}
+    </InsetText>
+  );
+}

package/src/theme/AnnouncementBar/index.js

@@ -0,0 +1,5 @@
+import React from 'react';
+
+export default function AnnouncementBar() {
+  return null;
+}

package/src/theme/CodeBlock/index.js

@@ -0,0 +1,55 @@
+import React, {useState} from 'react';
+import {Highlight, themes} from 'prism-react-renderer';
+
+export default function CodeBlock({children, className: classNameProp, title}) {
+  const [copied, setCopied] = useState(false);
+
+  // Extract language from className (e.g. 'language-javascript')
+  const language = classNameProp
+    ? classNameProp.replace(/language-/, '')
+    : 'text';
+
+  const codeString = typeof children === 'string'
+    ? children.replace(/\n$/, '')
+    : '';
+
+  const handleCopy = () => {
+    navigator.clipboard.writeText(codeString).then(() => {
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    });
+  };
+
+  return (
+    <div className="app-code-block">
+      {title && (
+        <div className="app-code-block__title">
+          {title}
+        </div>
+      )}
+      <Highlight theme={themes.github} code={codeString} language={language}>
+        {({style, tokens, getLineProps, getTokenProps}) => (
+          <pre className="app-code-block__pre" style={style}>
+            <button
+              type="button"
+              onClick={handleCopy}
+              className="app-code-block__copy"
+              aria-label="Copy code to clipboard"
+            >
+              {copied ? 'Copied' : 'Copy'}
+            </button>
+            <code>
+              {tokens.map((line, i) => (
+                <div key={i} {...getLineProps({line})}>
+                  {line.map((token, key) => (
+                    <span key={key} {...getTokenProps({token})} />
+                  ))}
+                </div>
+              ))}
+            </code>
+          </pre>
+        )}
+      </Highlight>
+    </div>
+  );
+}

package/src/theme/DocItem/Content/index.js

@@ -0,0 +1,28 @@
+import React from 'react';
+import {useDoc} from '../docContext';
+import MDXContent from '@theme/MDXContent';
+
+// Render a synthetic title if needed
+function useSyntheticTitle() {
+  const {metadata, frontMatter, contentTitle} = useDoc();
+  const shouldRender =
+    !frontMatter.hide_title && typeof contentTitle === 'undefined';
+  if (!shouldRender) {
+    return null;
+  }
+  return metadata.title;
+}
+
+export default function DocItemContent({children}) {
+  const syntheticTitle = useSyntheticTitle();
+  return (
+    <>
+      {syntheticTitle && (
+        <header>
+          <h1 className="govuk-heading-xl">{syntheticTitle}</h1>
+        </header>
+      )}
+      <MDXContent>{children}</MDXContent>
+    </>
+  );
+}

package/src/theme/DocItem/Footer/index.js

@@ -0,0 +1,5 @@
+import React from 'react';
+
+export default function DocItemFooter() {
+  return null;
+}

package/src/theme/DocItem/Layout/index.js

@@ -0,0 +1,10 @@
+import React from 'react';
+import DocItemContent from '@theme/DocItem/Content';
+
+export default function DocItemLayout({children}) {
+  return (
+    <article className="app-prose-scope">
+      <DocItemContent>{children}</DocItemContent>
+    </article>
+  );
+}

package/src/theme/DocItem/Metadata/index.js

@@ -0,0 +1,17 @@
+import React from 'react';
+import Head from '@docusaurus/Head';
+import {useDoc} from '../docContext';
+
+export default function DocItemMetadata() {
+  const {metadata} = useDoc();
+  const {title, description} = metadata;
+
+  return (
+    <Head>
+      {title && <title>{title}</title>}
+      {description && <meta name="description" content={description} />}
+      {title && <meta property="og:title" content={title} />}
+      {description && <meta property="og:description" content={description} />}
+    </Head>
+  );
+}

package/src/theme/DocItem/Paginator/index.js

@@ -0,0 +1,36 @@
+import React from 'react';
+import {useDoc} from '../docContext';
+
+export default function DocItemPaginator() {
+  const {metadata} = useDoc();
+  const {previous, next} = metadata;
+
+  if (!previous && !next) {
+    return null;
+  }
+
+  return (
+    <nav className="app-pagination govuk-!-margin-top-8" aria-label="Pagination">
+      <div className="app-pagination__container">
+        {previous ? (
+          <div className="app-pagination__prev">
+            <span className="govuk-body-s app-text-secondary">Previous</span>
+            <br />
+            <a href={previous.permalink} className="govuk-link">
+              {previous.title}
+            </a>
+          </div>
+        ) : <div />}
+        {next ? (
+          <div className="app-pagination__next">
+            <span className="govuk-body-s app-text-secondary">Next</span>
+            <br />
+            <a href={next.permalink} className="govuk-link">
+              {next.title}
+            </a>
+          </div>
+        ) : <div />}
+      </div>
+    </nav>
+  );
+}

package/src/theme/DocItem/TOC/Desktop/index.js

@@ -0,0 +1,5 @@
+import React from 'react';
+
+export default function TOCDesktop() {
+  return null;
+}

package/src/theme/DocItem/TOC/Mobile/index.js

@@ -0,0 +1,5 @@
+import React from 'react';
+
+export default function TOCMobile() {
+  return null;
+}

package/src/theme/DocItem/docContext.js

@@ -0,0 +1,37 @@
+import React, {createContext, useContext} from 'react';
+
+const DocContext = createContext(null);
+
+/**
+ * Lightweight DocProvider that works across Docusaurus 3.x versions.
+ * Replaces the version-specific DocProvider from @docusaurus/plugin-content-docs/client
+ * which was only added in Docusaurus 3.5+.
+ */
+export function DocProvider({content, children}) {
+  const Content = content;
+  const value = {
+    content: Content,
+    metadata: Content.metadata || {},
+    frontMatter: Content.frontMatter || {},
+    contentTitle: Content.contentTitle,
+    assets: Content.assets || {},
+  };
+
+  return (
+    <DocContext.Provider value={value}>
+      {children}
+    </DocContext.Provider>
+  );
+}
+
+/**
+ * Hook to access doc data from DocProvider context.
+ * Replaces the version-specific useDoc() from @docusaurus/plugin-content-docs/client.
+ */
+export function useDoc() {
+  const ctx = useContext(DocContext);
+  if (!ctx) {
+    throw new Error('useDoc() must be used within a <DocProvider>');
+  }
+  return ctx;
+}

package/src/theme/DocItem/index.js

@@ -0,0 +1,22 @@
+import React from 'react';
+import {DocProvider} from './docContext';
+import DocItemMetadata from '@theme/DocItem/Metadata';
+import DocItemLayout from '@theme/DocItem/Layout';
+
+/**
+ * DocItem — wraps a single doc page.
+ * Uses our own DocProvider (not the version-specific one from
+ * @docusaurus/plugin-content-docs/client which requires 3.5+).
+ */
+export default function DocItem(props) {
+  const {content: Content} = props;
+
+  return (
+    <DocProvider content={Content}>
+      <DocItemMetadata />
+      <DocItemLayout>
+        <Content />
+      </DocItemLayout>
+    </DocProvider>
+  );
+}

package/src/theme/DocPage/Layout/index.js

@@ -0,0 +1,5 @@
+import React from 'react';
+
+export default function DocPageLayout({children}) {
+  return <>{children}</>;
+}

package/src/theme/DocRoot/Layout/index.js

@@ -0,0 +1,10 @@
+import React from 'react';
+import Layout from '@theme/Layout';
+
+export default function DocRootLayout({children}) {
+  return (
+    <Layout>
+      {children}
+    </Layout>
+  );
+}

package/src/theme/DocRoot/index.js

@@ -0,0 +1,18 @@
+import React from 'react';
+import renderRoutes from '@docusaurus/renderRoutes';
+import DocRootLayout from '@theme/DocRoot/Layout';
+
+/**
+ * DocRoot — version-independent wrapper for the doc routes.
+ * Does not depend on useDocRootMetadata/DocsSidebarProvider
+ * which are only available in Docusaurus 3.5+.
+ * Instead, it renders the matched child routes directly,
+ * wrapped in the DocRootLayout (which includes the GOV.UK shell).
+ */
+export default function DocRoot({route}) {
+  return (
+    <DocRootLayout>
+      {renderRoutes(route.routes)}
+    </DocRootLayout>
+  );
+}

package/src/theme/DocVersionRoot/index.js

@@ -0,0 +1,6 @@
+import React from 'react';
+import renderRoutes from '@docusaurus/renderRoutes';
+
+export default function DocVersionRoot({route}) {
+  return renderRoutes(route.routes);
+}

package/src/theme/DocsRoot/index.js

@@ -0,0 +1,6 @@
+import React from 'react';
+import renderRoutes from '@docusaurus/renderRoutes';
+
+export default function DocsRoot({route}) {
+  return renderRoutes(route.routes);
+}

package/src/theme/Heading/index.js

@@ -0,0 +1,29 @@
+import React from 'react';
+
+const headingClasses = {
+  h1: 'govuk-heading-xl',
+  h2: 'govuk-heading-l',
+  h3: 'govuk-heading-m',
+  h4: 'govuk-heading-s',
+  h5: 'govuk-heading-s',
+  h6: 'govuk-heading-s',
+};
+
+export default function Heading({as: Tag = 'h2', id, children, ...props}) {
+  const className = headingClasses[Tag] || 'govuk-heading-m';
+
+  return (
+    <Tag id={id} className={className} {...props}>
+      {children}
+      {id && (
+        <a
+          href={`#${id}`}
+          className="govuk-link app-heading-anchor"
+          aria-label={`Direct link to ${typeof children === 'string' ? children : 'heading'}`}
+        >
+          #
+        </a>
+      )}
+    </Tag>
+  );
+}

package/src/theme/Homepage/index.js

@@ -0,0 +1,47 @@
+import React from 'react';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import Layout from '@theme/Layout';
+
+export default function Homepage() {
+  const {siteConfig} = useDocusaurusContext();
+  const baseUrl = useBaseUrl('/');
+
+  return (
+    <Layout title={siteConfig.title} description={siteConfig.tagline}>
+      <div className="govuk-grid-row">
+        <div className="govuk-grid-column-two-thirds">
+          <h1 className="govuk-heading-xl govuk-!-margin-top-8">
+            {siteConfig.title}
+          </h1>
+
+          {siteConfig.tagline && (
+            <p className="govuk-body-l">
+              {siteConfig.tagline}
+            </p>
+          )}
+
+          <a
+            href={baseUrl}
+            role="button"
+            draggable="false"
+            className="govuk-button govuk-button--start govuk-!-margin-top-4"
+          >
+            Get started
+            <svg
+              className="govuk-button__start-icon"
+              xmlns="http://www.w3.org/2000/svg"
+              width="17.5"
+              height="19"
+              viewBox="0 0 33 40"
+              aria-hidden="true"
+              focusable="false"
+            >
+              <path fill="currentColor" d="M0 0h13l20 20-20 20H0l20-20z" />
+            </svg>
+          </a>
+        </div>
+      </div>
+    </Layout>
+  );
+}

package/src/theme/Layout/Provider/index.js

@@ -0,0 +1,5 @@
+import React from 'react';
+
+export default function LayoutProvider({children}) {
+  return <>{children}</>;
+}

package/src/theme/Layout/index.js

@@ -0,0 +1,181 @@
+import React from 'react';
+import {SkipLink, Header, Footer, PhaseBanner, ServiceNavigation, NavigationMenu} from '@not-govuk/simple-components';
+import {useLocation} from '@docusaurus/router';
+import Head from '@docusaurus/Head';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import LayoutProvider from '@theme/Layout/Provider';
+import AnnouncementBar from '@theme/AnnouncementBar';
+
+// Read GOV.UK config from themeConfig
+function useGovukConfig() {
+  const {siteConfig} = useDocusaurusContext();
+  return siteConfig.themeConfig?.govuk || {};
+}
+
+// Strip the Docusaurus baseUrl prefix from a pathname
+function stripBaseUrl(pathname, baseUrl) {
+  if (baseUrl === '/') return pathname;
+  const prefix = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+  if (pathname.startsWith(prefix)) {
+    const stripped = pathname.slice(prefix.length);
+    return stripped || '/';
+  }
+  return pathname;
+}
+
+// Resolve sidebar paths.
+// Paths starting with '/' are absolute (from site root).
+// Paths without '/' are relative to the section's basePath.
+function resolvePath(basePath, relativePath) {
+  // Absolute path — return as-is
+  if (relativePath.startsWith('/')) return relativePath;
+  // Relative to root
+  if (basePath === '/') return `/${relativePath}`;
+  // Relative to section
+  const cleanBase = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
+  return `${cleanBase}/${relativePath}`;
+}
+
+// Resolve all paths in sidebar items
+function resolveSidebarPaths(items, basePath) {
+  return items.map(item => {
+    const resolvedItem = {
+      ...item,
+      href: resolvePath(basePath, item.href),
+    };
+    if (item.items && item.items.length > 0) {
+      resolvedItem.items = item.items.map(nestedItem => ({
+        ...nestedItem,
+        href: resolvePath(resolvedItem.href, nestedItem.href),
+      }));
+    }
+    return resolvedItem;
+  });
+}
+
+// Find the active navigation section based on current path
+function getActiveSection(pathname, navigation) {
+  return navigation.find(section => {
+    if (!section.sidebar) return false;
+    // Use the section's configured href as the base path
+    const basePath = section.href || '/';
+    const resolvedSidebar = resolveSidebarPaths(section.sidebar, basePath);
+    return resolvedSidebar.some(item => {
+      if (pathname === item.href) return true;
+      if (item.items) {
+        return item.items.some(nestedItem => pathname === nestedItem.href);
+      }
+      return false;
+    });
+  });
+}
+
+export default function Layout(props) {
+  const location = useLocation();
+  const {siteConfig} = useDocusaurusContext();
+  const govukConfig = siteConfig.themeConfig?.govuk || {};
+  const {
+    children,
+    title,
+    description,
+    noFooter,
+  } = props;
+
+  const navigation = govukConfig.navigation || [];
+  const header = govukConfig.header || {};
+  const phaseBanner = govukConfig.phaseBanner;
+  const footer = govukConfig.footer || {};
+
+  // Strip baseUrl so sidebar matching works regardless of deployment path
+  const pathname = stripBaseUrl(location.pathname, siteConfig.baseUrl);
+  const baseUrl = siteConfig.baseUrl.endsWith('/')
+    ? siteConfig.baseUrl.slice(0, -1)
+    : siteConfig.baseUrl;
+
+  // Prepend baseUrl to a site-root path for use in actual links
+  function withBase(href) {
+    if (!href || href.startsWith('http')) return href;
+    return `${baseUrl}${href.startsWith('/') ? href : `/${href}`}`;
+  }
+
+  // Get active section for sidebar
+  const activeSection = getActiveSection(pathname, navigation);
+  const basePath = activeSection?.href || '/';
+  const sidebarItems = activeSection?.sidebar
+    ? resolveSidebarPaths(activeSection.sidebar, basePath).map(item => ({
+        ...item,
+        href: withBase(item.href),
+        ...(item.items && {
+          items: item.items.map(nested => ({...nested, href: withBase(nested.href)})),
+        }),
+      }))
+    : null;
+
+  // Convert navigation to service navigation format (Level 1 only)
+  const serviceNavItems = navigation.map(item => ({
+    href: withBase(item.href),
+    text: item.text,
+  }));
+
+  return (
+    <LayoutProvider>
+      <Head>
+        <html lang="en-GB" className="govuk-template" />
+        <body className="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">
+        <AnnouncementBar />
+
+        {/* Hidden navbar element for Docusaurus hooks */}
+        <nav className="navbar" style={{display: 'none'}} />
+
+        <SkipLink for="main-content">Skip to main content</SkipLink>
+
+        <Header
+          govUK
+          rebrand
+          serviceName={header.serviceName}
+          serviceHref={withBase(header.serviceHref || '/')}
+        />
+
+        <ServiceNavigation items={serviceNavItems} />
+
+        <div className="govuk-width-container">
+          {phaseBanner && (
+            <PhaseBanner phase={phaseBanner.phase}>
+              {phaseBanner.text}{' '}
+              {phaseBanner.feedbackHref && (
+                <a href={phaseBanner.feedbackHref} className="govuk-link">
+                  feedback
+                </a>
+              )}
+            </PhaseBanner>
+          )}
+
+          <main id="main-content" className="govuk-main-wrapper">
+            {sidebarItems ? (
+              <div className="app-layout-sidebar">
+                <aside className="app-layout-sidebar__nav">
+                  <NavigationMenu items={sidebarItems} />
+                </aside>
+                <div className="app-layout-sidebar__content">
+                  {children}
+                </div>
+              </div>
+            ) : (
+              children
+            )}
+          </main>
+        </div>
+
+        {!noFooter && (
+          <Footer govUK rebrand meta={footer.meta} />
+        )}
+      </div>
+    </LayoutProvider>
+  );
+}