docs: add componentSecrets support and document PaymentField secrets

Adds a named componentSecrets feature to the doc generation script so
components can declare what per-form secrets they require. Generates a
standard "Required secrets" section with a getFormSecret blurb and a
secrets table. PaymentField is the first consumer.

Also clarifies in custom-services.md that getFormSecret is per-form
scoped, distinct from global plugin options such as ordnanceSurveyApiKey,
and safe to leave unimplemented when no secret-using components are present.

Author: alexluckett

docs/features/code-based/custom-services.md

@@ -15,7 +15,9 @@ interface FormsService {
 }
 ```
 
-`getFormMetadata` is called on every request and should be fast. `getFormDefinition` is only called when the metadata signals the definition has changed, so it can be slower. `getFormMetadataById` is called by the status page to retrieve the submitted form's name by its ID — this allows the confirmation panel to display the correct form name even when the current URL belongs to a different form (for example, a shared feedback form). `getFormSecret` is used by components that need secrets (such as API keys) stored outside the form definition.
+`getFormMetadata` is called on every request and should be fast. `getFormDefinition` is only called when the metadata signals the definition has changed, so it can be slower. `getFormMetadataById` is called by the status page to retrieve the submitted form's name by its ID — this allows the confirmation panel to display the correct form name even when the current URL belongs to a different form (for example, a shared feedback form).
+
+`getFormSecret` retrieves a secret that belongs to a specific form — for example, a payment API key scoped to that form. This is distinct from global secrets such as `ordnanceSurveyApiKey` and `ordnanceSurveyApiSecret`, which are passed once at plugin registration and apply across all forms. If your forms do not use any components that require per-form secrets, this method will never be called and you can safely return `undefined` (or leave it unimplemented). See the documentation for each component to find out whether it requires secrets and what names it requests.
 
 ### Loading forms from files
 

scripts/component-metadata.json

@@ -115,6 +115,18 @@
       "This component renders an inline Ordnance Survey map that lets users click a location to auto-populate the coordinate inputs across multiple coordinate formats. The map requires the `ordnanceSurveyApiKey` and `ordnanceSurveyApiSecret` [plugin options](../../plugin-options.md#geospatial-map) to be set — without them the component falls back to plain text inputs."
     ]
   },
+  "componentSecrets": {
+    "PaymentField": [
+      {
+        "name": "payment-test-api-key",
+        "description": "GOV.UK Pay API key used when the form is in test or draft mode."
+      },
+      {
+        "name": "payment-live-api-key",
+        "description": "GOV.UK Pay API key used when the form is in live mode."
+      }
+    ]
+  },
   "pageProperties": {
     "components": "Array of component definitions rendered on the page.",
     "condition": "Name of a condition that controls whether this page is shown.",

scripts/generate-component-docs.js

@@ -733,6 +733,7 @@ export function generateComponentMd(
   const { options = [], schema = [], props = [] } = interfaceData
 
   const links = metadata.componentLinks?.[componentName] ?? []
+  const secrets = metadata.componentSecrets?.[componentName] ?? []
 
   // leading '' ensures a blank line between frontmatter and the import
   // Level 1 components require client-side JavaScript to render and can't be statically previewed
@@ -821,6 +822,20 @@ export function generateComponentMd(
     lines.push(``)
   }
 
+  if (secrets.length > 0) {
+    lines.push(`## Required secrets`, ``)
+    lines.push(
+      `This component retrieves secrets at runtime via [\`getFormSecret\`](../../code-based/custom-services.md#formsservice) on your \`formsService\`. Implement it to return the correct value from your secrets store — do not use environment variables or plugin options for per-form secrets.`,
+      ``
+    )
+    lines.push(`| Secret name | Description |`)
+    lines.push(`|---|---|`)
+    for (const secret of secrets) {
+      lines.push(`| \`${secret.name}\` | ${secret.description} |`)
+    }
+    lines.push(``)
+  }
+
   return lines.join('\n')
 }
 

scripts/generate-component-docs.test.js

@@ -47,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.","SummaryPageController":"Summary page type."},"properties":{"rows":"Number of rows for the textarea."},"pageProperties":{"repeat.options.name":"Identifier for the repeatable section."}}'
+      return '{"components":{"TextField":"Single-line text input.","PaymentField":"Redirects the user to GOV.UK Pay."},"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."},"componentSecrets":{"PaymentField":[{"name":"payment-test-api-key","description":"GOV.UK Pay API key for test mode."},{"name":"payment-live-api-key","description":"GOV.UK Pay API key for live mode."}]}}'
     }
     return ''
   }),
@@ -436,6 +436,24 @@ describe('Component Documentation Generator', () => {
     })
   })
 
+  describe('generateComponentMd with componentSecrets', () => {
+    const interfaceData = { options: [], schema: [], props: [] }
+
+    it('renders a Required secrets section with blurb and table when secrets are defined', () => {
+      const result = generateComponentMd('PaymentField', interfaceData, 1)
+      expect(result).toContain('## Required secrets')
+      expect(result).toContain('`getFormSecret`')
+      expect(result).toContain('`payment-test-api-key`')
+      expect(result).toContain('`payment-live-api-key`')
+    })
+
+    it('omits Required secrets section for components with no secrets', () => {
+      const result = generateComponentMd('TextField', interfaceData, 1)
+      expect(result).not.toContain('## Required secrets')
+      expect(result).not.toContain('getFormSecret')
+    })
+  })
+
   describe('buildJsNotice', () => {
     it('Level 1: renders a GOV.UK notification banner with banner structure', () => {
       const result = buildJsNotice(1, 'Notice text.')