Merge branch 'main' into docs/page-elements

Author: jbarnsley10

docs/assets/css/docusaurus.scss

@@ -80,6 +80,39 @@
   color: #505a5f;
 }
 
+.app-page-preview__header {
+  background: #1d70b8;
+  padding: 10px 20px;
+  display: flex;
+  align-items: center;
+  margin-bottom: 0;
+}
+
+.app-page-preview__service-name {
+  color: #ffffff;
+  font-weight: 700;
+  font-size: 16px;
+  font-family: sans-serif;
+}
+
+.app-page-preview__main {
+  padding: 20px;
+  background: #ffffff;
+}
+
+.app-page-preview__footer {
+  background: #f3f2f1;
+  border-top: 1px solid #b1b4b6;
+  padding: 10px 20px;
+  font-size: 14px;
+  color: #505a5f;
+  font-family: sans-serif;
+}
+
+.component-preview--page {
+  padding: 0;
+}
+
 @media (min-width: 48.125em) {
   .govuk-template--rebranded .app-masthead .govuk-grid-row {
     display: flex;

scripts/generate-component-docs.js

@@ -7,6 +7,8 @@ import ts from 'typescript'
 
 import { fixtures } from './component-preview-fixtures.js'
 import { writePreviewPartial } from './generate-component-previews.js'
+import { writePagePreviewPartial } from './generate-page-previews.js'
+import { pageFixtures } from './page-preview-fixtures.js'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
@@ -863,12 +865,14 @@ export function controllerSlug(controllerKey) {
  * @param {string} controllerKey
  * @param {Array<{name: string, type: string, optional: boolean}>} uniqueProps
  * @param {string} [examplePath]
+ * @param {Array<object>|null} [exampleComponents]
  * @returns {Record<string, unknown>}
  */
 export function generatePageExample(
   controllerKey,
   uniqueProps,
-  examplePath = '/page-path'
+  examplePath = '/page-path',
+  exampleComponents = null
 ) {
   const controllerValue =
     controllerKey === 'PageController' ? null : controllerKey
@@ -886,6 +890,8 @@ export function generatePageExample(
     setNestedValue(example, prop.name, placeholderForType(prop.type))
   }
 
+  if (exampleComponents) example.components = exampleComponents
+
   return example
 }
 
@@ -894,12 +900,16 @@ export function generatePageExample(
  * @param {Array<{name: string, type: string, optional: boolean}>} uniqueProps
  * @param {string} examplePath
  * @param {number} sidebarPosition
+ * @param {string|null} [previewSlug]
+ * @param {Array<object>|null} [exampleComponents]
  */
-function generatePageMd(
+export function generatePageMd(
   controllerKey,
   uniqueProps,
   examplePath,
-  sidebarPosition
+  sidebarPosition,
+  previewSlug = null,
+  exampleComponents = null
 ) {
   const description = metadata.pages[controllerKey]
   if (!description) return null
@@ -908,11 +918,16 @@ function generatePageMd(
   const isDefault = controllerKey === 'PageController'
   const links = metadata.pageLinks?.[controllerKey] ?? []
 
+  const previewImport = previewSlug
+    ? [``, `import Preview from './_previews/${previewSlug}.mdx'`]
+    : []
+
   const lines = [
     `---`,
     `sidebar_label: "${label}"`,
     `sidebar_position: ${sidebarPosition}`,
     `---`,
+    ...previewImport,
     ``,
     `# ${label}`,
     ``,
@@ -933,12 +948,21 @@ function generatePageMd(
     lines.push(`**Controller value:** \`"${controllerKey}"\``, ``)
   }
 
+  if (previewSlug) {
+    lines.push(`## Preview`, ``, `<Preview />`, ``)
+  }
+
   lines.push(
     `## JSON definition`,
     ``,
     '```json',
     JSON.stringify(
-      generatePageExample(controllerKey, uniqueProps, examplePath),
+      generatePageExample(
+        controllerKey,
+        uniqueProps,
+        examplePath,
+        exampleComponents
+      ),
       null,
       2
     ),
@@ -1032,7 +1056,7 @@ function generatePagesIndex() {
   for (const [key, description] of Object.entries(metadata.pages)) {
     const label = controllerLabel(key)
     const slug = controllerSlug(key)
-    lines.push(`- [**${label}**](./${slug}.md) — ${description}`)
+    lines.push(`- [**${label}**](./${slug}.mdx) — ${description}`)
   }
 
   lines.push(``)
@@ -1092,6 +1116,8 @@ function main() {
     fs.rmSync(pagesOutputDir, { recursive: true, force: true })
   }
   fs.mkdirSync(pagesOutputDir, { recursive: true })
+  const pagePreviewsDir = path.resolve(pagesOutputDir, '_previews')
+  fs.mkdirSync(pagePreviewsDir, { recursive: true })
 
   // Parse sources
   const interfaces = parseComponentInterfaces(componentsDtsPath)
@@ -1180,13 +1206,25 @@ function main() {
     }
     const { props: uniqueProps = [], examplePath = '/page-path' } =
       pageInterfaces[key] ?? {}
-    const content = generatePageMd(key, uniqueProps, examplePath, i + 1)
+    const fixture = pageFixtures[key]
+    const sidebarPosition = i + 1
+    const content = generatePageMd(
+      key,
+      uniqueProps,
+      examplePath,
+      sidebarPosition,
+      fixture ? slug : null,
+      fixture?.exampleComponents ?? null
+    )
     if (content) {
-      fs.writeFileSync(path.join(pagesOutputDir, `${slug}.md`), content)
+      fs.writeFileSync(path.join(pagesOutputDir, `${slug}.mdx`), content)
+    }
+    if (fixture) {
+      writePagePreviewPartial(pagePreviewsDir, slug, fixture)
     }
   }
 
-  fs.writeFileSync(path.join(pagesOutputDir, 'index.md'), generatePagesIndex())
+  fs.writeFileSync(path.join(pagesOutputDir, 'index.mdx'), generatePagesIndex())
 
   console.log(
     `Generated ${componentOrder.length} component pages and ${Object.keys(metadata.pages).length} page type pages.`

scripts/generate-component-docs.test.js

@@ -30,6 +30,14 @@ jest.mock('./component-preview-fixtures.js', () => ({
   fixtures: {}
 }))
 
+jest.mock('./generate-page-previews.js', () => ({
+  writePagePreviewPartial: jest.fn()
+}))
+
+jest.mock('./page-preview-fixtures.js', () => ({
+  pageFixtures: {}
+}))
+
 // jest.mock factories are hoisted before variable declarations, so the
 // component-metadata.json payload must be inlined rather than referenced.
 jest.mock('fs', () => ({
@@ -39,7 +47,7 @@ jest.mock('fs', () => ({
   readdirSync: jest.fn(),
   readFileSync: jest.fn().mockImplementation((filePath) => {
     if (String(filePath ?? '').includes('component-metadata.json')) {
-      return '{"components":{"TextField":"Single-line text input."},"pages":{"PageController":"The default page type.","RepeatPageController":"Allows repeated answers."},"properties":{"rows":"Number of rows for the textarea."},"pageProperties":{"repeat.options.name":"Identifier for the repeatable section."}}'
+      return '{"components":{"TextField":"Single-line text input."},"pages":{"PageController":"The default page type.","RepeatPageController":"Allows repeated answers.","SummaryPageController":"Summary page type."},"properties":{"rows":"Number of rows for the textarea."},"pageProperties":{"repeat.options.name":"Identifier for the repeatable section."}}'
     }
     return ''
   }),
@@ -55,6 +63,7 @@ import {
   generateComponentMd,
   generateExample,
   generatePageExample,
+  generatePageMd,
   placeholderForType,
   setNestedValue,
   simplifyType,
@@ -287,6 +296,83 @@ describe('Component Documentation Generator', () => {
       expect(result.repeat.options.name).toBe('')
       expect(result.repeat).not.toHaveProperty('schema')
     })
+
+    it('injects exampleComponents into the example when provided', () => {
+      const components = [
+        {
+          type: 'FileUploadField',
+          name: 'upload',
+          title: 'Upload a document',
+          options: {},
+          schema: {}
+        }
+      ]
+      const result = generatePageExample(
+        'FileUploadPageController',
+        [],
+        '/file-upload',
+        components
+      )
+      expect(result.components).toEqual(components)
+    })
+
+    it('does not add components when exampleComponents is null', () => {
+      const result = generatePageExample(
+        'PageController',
+        [],
+        '/page-path',
+        null
+      )
+      expect(result).not.toHaveProperty('components')
+    })
+  })
+
+  describe('generatePageMd with preview', () => {
+    it('includes preview import when previewSlug is provided', () => {
+      const result = generatePageMd(
+        'PageController',
+        [],
+        '/page-path',
+        1,
+        'page-controller'
+      )
+      expect(result).toContain(
+        "import Preview from './_previews/page-controller.mdx'"
+      )
+    })
+
+    it('includes ## Preview section and <Preview /> when previewSlug is provided', () => {
+      const result = generatePageMd(
+        'PageController',
+        [],
+        '/page-path',
+        1,
+        'page-controller'
+      )
+      expect(result).toContain('## Preview')
+      expect(result).toContain('<Preview />')
+    })
+
+    it('places ## Preview before ## JSON definition', () => {
+      const result = generatePageMd(
+        'SummaryPageController',
+        [],
+        '/summary',
+        1,
+        'summary-page-controller'
+      )
+      const previewIdx = result.indexOf('## Preview')
+      const jsonIdx = result.indexOf('## JSON definition')
+      expect(previewIdx).toBeGreaterThan(-1)
+      expect(previewIdx).toBeLessThan(jsonIdx)
+    })
+
+    it('omits import, ## Preview, and <Preview /> when previewSlug is absent', () => {
+      const result = generatePageMd('PageController', [], '/page-path', 1)
+      expect(result).not.toContain('import Preview')
+      expect(result).not.toContain('## Preview')
+      expect(result).not.toContain('<Preview />')
+    })
   })
 
   describe('controllerLabel', () => {

scripts/generate-component-previews.js

@@ -50,9 +50,10 @@ export function renderComponent(fixture) {
 /**
  * Build the MDX partial content from one or more rendered HTML strings.
  * @param {Array<{ label?: string, html: string }>} renders
+ * @param {string} [wrapperClass]
  * @returns {string}
  */
-export function buildPartialMdx(renders) {
+export function buildPartialMdx(renders, wrapperClass = 'component-preview') {
   return renders
     .map(({ label, html }) => {
       const escaped = html.replace(/`/g, '\\`').replace(/\$\{/g, '\\${')
@@ -67,7 +68,7 @@ export function buildPartialMdx(renders) {
       const labelLine = safeLabel
         ? `<h3 className="govuk-heading-s">${safeLabel}</h3>\n`
         : ''
-      return `${labelLine}<div className="component-preview">\n  <div dangerouslySetInnerHTML={{ __html: \`${escaped}\` }} />\n</div>`
+      return `${labelLine}<div className="${wrapperClass}">\n  <div dangerouslySetInnerHTML={{ __html: \`${escaped}\` }} />\n</div>`
     })
     .join('\n\n')
 }

scripts/generate-component-previews.test.js

@@ -116,6 +116,17 @@ describe('buildPartialMdx', () => {
     expect(result).toContain('\\`backtick\\`')
     expect(result).toContain('\\' + dollarBrace + 'expr}')
   })
+
+  it('uses custom wrapperClass when provided', () => {
+    const result = buildPartialMdx(
+      [{ html: '<input>' }],
+      'component-preview component-preview--page'
+    )
+    expect(result).toContain(
+      'className="component-preview component-preview--page"'
+    )
+    expect(result).not.toContain('className="component-preview"')
+  })
 })
 
 describe('renderComponent', () => {

scripts/generate-page-previews.js

@@ -0,0 +1,61 @@
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+import { buildPartialMdx } from './generate-component-previews.js'
+
+import { environment } from '~/src/server/plugins/nunjucks/environment.js'
+
+// Make preview-layout.html discoverable by name within the Nunjucks environment.
+const scriptsDir = fileURLToPath(new URL('.', import.meta.url))
+for (const loader of /** @type {any} */ (environment).loaders ?? []) {
+  if (loader.searchPaths) loader.searchPaths.push(scriptsDir)
+}
+
+/**
+ * Render a single page fixture context to an HTML string.
+ * Reads the view name from context.page.viewName — set automatically by the
+ * real page controller via getViewModel, or manually on the page stub for
+ * fixtures that don't use pageViewContext.
+ * Passes baseLayoutPath to strip the GOV.UK page wrapper.
+ * @param {PageViewModelBase} context
+ * @returns {string}
+ */
+export function renderPage(context) {
+  const html = environment.render(`${context.page.viewName}.html`, {
+    ...context,
+    baseLayoutPath: 'preview-layout.html'
+  })
+  // Neutralise interactive elements — this is documentation, not a working service.
+  return html
+    .replace(/<form\b[^>]*>/g, '<div class="app-page-preview__form">')
+    .replace(/<\/form>/g, '</div>')
+    .replace(/href="[^"]*"/g, 'href="#"')
+}
+
+/**
+ * Renders all variants (or single context) for a page fixture and writes the
+ * MDX partial to previewsDir/<slug>.mdx.
+ * @param {string} previewsDir
+ * @param {string} slug
+ * @param {{ context?: PageViewModelBase, variants?: Array<{label: string, context: PageViewModelBase}> }} fixture
+ */
+export function writePagePreviewPartial(previewsDir, slug, fixture) {
+  fs.mkdirSync(previewsDir, { recursive: true })
+
+  const renders = fixture.variants
+    ? fixture.variants.map(({ label, context }) => ({
+        label,
+        html: renderPage(context)
+      }))
+    : [{ html: renderPage(/** @type {PageViewModelBase} */ (fixture.context)) }]
+
+  fs.writeFileSync(
+    path.join(previewsDir, `${slug}.mdx`),
+    buildPartialMdx(renders, 'component-preview component-preview--page')
+  )
+}
+
+/**
+ * @typedef {import('~/src/server/plugins/engine/types.js').PageViewModelBase} PageViewModelBase
+ */