From b704429112cdf6dd6a0c12f73e27cce2bf3e2fdb Mon Sep 17 00:00:00 2001
From: MobileMage <aidelojejoshua@gmail.com>
Date: Sun, 4 Oct 2026 02:07:42 +0100
Subject: [PATCH 1/4] chore: pin the js and spec submodules to the field
 release

The js repo now holds the postcode field and its React wrapper, and
the spec repo defines the field and its message catalogue in version
0.3.0. The glossary of the spec gained three terms, so the local copy
follows it.

Signed-off-by: MobileMage <aidelojejoshua@gmail.com>
---
 CONTEXT.md | 12 ++++++++++++
 js         |  2 +-
 spec       |  2 +-
 3 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/CONTEXT.md b/CONTEXT.md
index fcc8182..4b82f5f 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -169,6 +169,18 @@ _Avoid_: input, widget, picker
 To show the user what a postcode points to before the app stores it.
 _Avoid_: verify, validate (for this step)
 
+**Check status**:
+What the WooCommerce plugin learned about the postcode of an order: `valid`, `invalid`, `unchecked` or `error`. The order meta `_gatepost_postcode_check` holds it.
+_Avoid_: verification status, validation result
+
+**Form value**:
+The text that a field gives its form when the form is sent: the canonical form of a postcode, the 6 digits of a legacy postcode, or the text without white space at the start and the end.
+_Avoid_: submitted value, output
+
+**Message catalogue**:
+A data file that holds the text of a UI in one language, one message for each key.
+_Avoid_: strings file, translations, locale file
+
 **Tell**:
 A habit that makes code look machine-written, such as very long lines.
 _Avoid_: smell (smells are design problems), anti-pattern
diff --git a/js b/js
index 3ba7fc4..0003151 160000
--- a/js
+++ b/js
@@ -1 +1 @@
-Subproject commit 3ba7fc43c4f1c15685987e88ce20cd190f95065d
+Subproject commit 00031516fc5b313e2ea2870fd3ae537a4c309f4a
diff --git a/spec b/spec
index 9e20f87..db359cd 160000
--- a/spec
+++ b/spec
@@ -1 +1 @@
-Subproject commit 9e20f87addb2a2b238cea82d65b9bd071bedc3f6
+Subproject commit db359cde28a7c5c549f1a3069f20078f19f05a58

From 63b21f45e6222c9a294ca764693087e9a1b13f35 Mon Sep 17 00:00:00 2001
From: MobileMage <aidelojejoshua@gmail.com>
Date: Sun, 4 Oct 2026 02:07:42 +0100
Subject: [PATCH 2/4] docs: add the quickstarts for the HTML field and React

Most sites add a postcode through a form, so the field and the React
wrapper need their own quickstarts. Each HTML, TSX and CSS block on
these pages is a README example that the js repo runs in its CI, and a
test fails when a page shows a block that no README holds. A browser
test also loads each HTML example against the built element, with the
mock gateway and no other host. The API reference now covers both
packages, and the spec section shows the field spec.

Signed-off-by: MobileMage <aidelojejoshua@gmail.com>
---
 astro.config.mjs                    |  11 +-
 package.json                        |   2 +-
 scripts/spec-pages.ts               |   6 ++
 src/content/docs/guides/html.md     | 152 ++++++++++++++++++++++++++++
 src/content/docs/guides/react.md    |  84 +++++++++++++++
 src/content/docs/start.md           |   2 +
 test/browser/field-examples.spec.ts |  86 ++++++++++++++++
 test/site/reference.test.ts         |   2 +-
 test/support/examples.ts            |   2 +-
 test/unit/examples.test.ts          |  31 +++++-
 test/unit/release-state.test.ts     |   2 +-
 test/unit/spec-pages.test.ts        |   4 +-
 12 files changed, 376 insertions(+), 8 deletions(-)
 create mode 100644 src/content/docs/guides/html.md
 create mode 100644 src/content/docs/guides/react.md
 create mode 100644 test/browser/field-examples.spec.ts

diff --git a/astro.config.mjs b/astro.config.mjs
index 205daad..17cc43f 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -14,6 +14,8 @@ const base = '/docs';
 
 const [coreTypeDoc, coreTypeDocGroup] = createStarlightTypeDocPlugin();
 const [clientTypeDoc, clientTypeDocGroup] = createStarlightTypeDocPlugin();
+const [fieldTypeDoc, fieldTypeDocGroup] = createStarlightTypeDocPlugin();
+const [reactTypeDoc, reactTypeDocGroup] = createStarlightTypeDocPlugin();
 
 // The API pages of a package, generated from the TSDoc comments of its source.
 function typeDocOf(name) {
@@ -95,7 +97,12 @@ export default defineConfig({
       // A code block that scrolls sideways needs a focus stop for keyboard users. Wrapped lines
       // need none, and they fit a phone screen.
       expressiveCode: { defaultProps: { wrap: true } },
-      plugins: [coreTypeDoc(typeDocOf('core')), clientTypeDoc(typeDocOf('client'))],
+      plugins: [
+        coreTypeDoc(typeDocOf('core')),
+        clientTypeDoc(typeDocOf('client')),
+        fieldTypeDoc(typeDocOf('field')),
+        reactTypeDoc(typeDocOf('react')),
+      ],
       sidebar: [
         { label: 'Start', items: ['start', 'playground'] },
         { label: 'Guides', items: [{ autogenerate: { directory: 'guides' } }] },
@@ -105,6 +112,8 @@ export default defineConfig({
           items: [
             coreTypeDocGroup,
             clientTypeDocGroup,
+            fieldTypeDocGroup,
+            reactTypeDocGroup,
             {
               label: 'gatepost/postcode',
               collapsed: true,
diff --git a/package.json b/package.json
index a754834..6f0be2b 100644
--- a/package.json
+++ b/package.json
@@ -10,7 +10,7 @@
   "scripts": {
     "sdk": "run-s sdk:js sdk:js:build sdk:php",
     "sdk:js": "pnpm --dir js install --frozen-lockfile",
-    "sdk:js:build": "pnpm --dir js --filter @gatepost/core --filter @gatepost/client run build",
+    "sdk:js:build": "pnpm --dir js --filter './packages/{core,client,field,react}' run build",
     "sdk:php": "composer --working-dir=php install --no-interaction --no-progress",
     "dev": "ASTRO_TELEMETRY_DISABLED=1 astro dev",
     "build": "ASTRO_TELEMETRY_DISABLED=1 astro build",
diff --git a/scripts/spec-pages.ts b/scripts/spec-pages.ts
index 9fcd76f..0726596 100644
--- a/scripts/spec-pages.ts
+++ b/scripts/spec-pages.ts
@@ -25,6 +25,12 @@ const SOURCES = [
     title: 'Client contract',
     description: "How every Gatepost client calls NIPOST's gateway: results, errors and retries.",
   },
+  {
+    file: 'field.md',
+    slug: 'field',
+    title: 'Field',
+    description: 'How every Gatepost postcode field behaves: settings, events, states and privacy.',
+  },
   {
     file: 'CONTEXT.md',
     slug: 'glossary',
diff --git a/src/content/docs/guides/html.md b/src/content/docs/guides/html.md
new file mode 100644
index 0000000..3851c90
--- /dev/null
+++ b/src/content/docs/guides/html.md
@@ -0,0 +1,152 @@
+---
+title: Add a postcode field to a web form
+description: Use the gatepost-postcode-field element in any HTML form, with or without a framework.
+sidebar:
+  label: HTML field
+  order: 4
+---
+
+`@gatepost/field` adds `<gatepost-postcode-field>`, a form field for Nigeria's digital postcode. It works in a plain HTML form. It checks the form of the postcode while the user types, and it can ask NIPOST's gateway about the postcode.
+
+## Install
+
+The first alpha is not published yet. This page will say when it is.
+
+```sh
+pnpm add @gatepost/field
+```
+
+Until the release, the CDN address in the examples below does not work. Import `@gatepost/field` once in your app, and the page can use the element. A page with no build step can load the one-file build from a CDN instead. After a release exists, pin its version in the CDN address of a production page.
+
+## Add the field
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@gatepost/field/dist/element.js"></script>
+<form action="/address">
+  <gatepost-postcode-field name="postcode" required></gatepost-postcode-field>
+  <button>Continue</button>
+</form>
+```
+
+The element is empty until the script runs, so the layout moves when it loads. A page with no JavaScript sends no postcode.
+
+A `<label for>` outside the element cannot name the input inside it. Give the text with the `label` attribute.
+
+A user who types `fc 01 z99 zz 01` sends `postcode=FC-01-Z99-ZZ-01`. With no key, the field checks the form offline and sends no request.
+
+## Check postcodes with NIPOST
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@gatepost/field/dist/element.js"></script>
+<form action="/address">
+  <gatepost-postcode-field name="postcode" api-key="nipost_pk_live_your_key" confirm="level2" gps>
+  </gatepost-postcode-field>
+  <button>Continue</button>
+</form>
+```
+
+Use a publishable key, which starts with `nipost_pk_`. Add your site to its allowed origins in NIPOST's dashboard. Anyone can read a key in a page, so the field refuses a secret key. It sends no request, and it writes one error to the console.
+
+A key holds a lookup level, and a call above it fails. The field then says that it could not check the postcode. A postcode that the gateway does not know, or a failed request, never stops the form. The gateway's data is new, so check the postcode again on your server.
+
+<div class="table-scroll" role="region" tabindex="0" aria-label="Table: Attributes of the field">
+
+| Attribute                               | Values                       | Default                             |
+| --------------------------------------- | ---------------------------- | ----------------------------------- |
+| `name`, `value`, `required`, `disabled` | as for a native input        | none                                |
+| `label`                                 | the visible label            | `Postcode`                          |
+| `api-key`                               | a publishable key            | none, so the field sends no request |
+| `base-url`                              | the gateway's address        | `https://api.postcode.gov.ng`       |
+| `confirm`                               | `none`, `level1` or `level2` | `level1`                            |
+| `gps`                                   | present or absent            | absent                              |
+| `legacy`                                | `accept` or `reject`         | `accept`                            |
+
+</div>
+
+With `gps`, a button puts the postcode of the user's location in the input. The field asks for the location only when the user presses the button. With `legacy="accept"`, the field also accepts an old 6-digit postcode.
+
+## Listen for changes
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@gatepost/field/dist/element.js"></script>
+<gatepost-postcode-field name="postcode"></gatepost-postcode-field>
+<output id="chosen"></output>
+<script type="module">
+  const field = document.querySelector('gatepost-postcode-field');
+  field.addEventListener('gatepost-change', (event) => {
+    document.querySelector('#chosen').value = event.detail.value;
+  });
+</script>
+```
+
+The events bubble, so a page can listen on the form. At level 2, `gatepost-confirm` gives the recent house address of the postcode. The field never shows it, and your page should not show it to the person who typed the postcode. That person can have typed any postcode.
+
+<div class="table-scroll" role="region" tabindex="0" aria-label="Table: Events of the field">
+
+| Event              | `detail`                                                                                        |
+| ------------------ | ----------------------------------------------------------------------------------------------- |
+| `gatepost-change`  | `value`, `postcode`, `source` (`typed`, `pasted`, `suggestion` or `gps`) and `accuracyM`        |
+| `gatepost-confirm` | `lookup`, the result of the lookup                                                              |
+| `gatepost-error`   | `code`, an error code of `@gatepost/client`, or `secret_key`, `gps_denied` or `gps_unavailable` |
+
+</div>
+
+## Change the words and the look
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@gatepost/field/dist/element.js"></script>
+<style>
+  gatepost-postcode-field {
+    --gatepost-accent: #5b2a86;
+  }
+</style>
+<gatepost-postcode-field name="postcode" required></gatepost-postcode-field>
+<script type="module">
+  const field = document.querySelector('gatepost-postcode-field');
+  field.messages = { label: 'Delivery postcode', empty: 'Enter the postcode of the delivery.' };
+</script>
+```
+
+The `messages` property replaces messages by key. The field keeps the English text for each key that you leave out. The [field spec](../../spec/field/) lists each key.
+
+The tokens are `--gatepost-text`, `--gatepost-muted`, `--gatepost-background`, `--gatepost-border`, `--gatepost-accent`, `--gatepost-error`, `--gatepost-warning`, `--gatepost-radius` and `--gatepost-font`. The parts `field`, `label`, `hint`, `input`, `message` and `button` take `::part()` rules.
+
+The default colours are for a light page. They meet a contrast of 4.5:1 on white. On a dark page, set the seven colour tokens, and check your own colours on the background of your page.
+
+```css
+gatepost-postcode-field {
+  --gatepost-text: #f2f5f4;
+  --gatepost-muted: #b9c2be;
+  --gatepost-background: #1c2321;
+  --gatepost-border: #8f9b96;
+  --gatepost-accent: #5ad1bf;
+  --gatepost-error: #ff9d94;
+  --gatepost-warning: #ffb95c;
+}
+```
+
+## What the field does not do
+
+- It stores nothing, sets no cookie and sends no telemetry.
+- It sends a request only for a whole postcode, and only when it has a publishable key. It sends a location request only after the user presses the location button.
+- It never shows a house address.
+
+## Requirements
+
+<div class="table-scroll" role="region" tabindex="0" aria-label="Table: Requirements of the field">
+
+| Requirement   | Version                                                    |
+| ------------- | ---------------------------------------------------------- |
+| Browser       | a current Chrome, Edge or Firefox, or Safari 16.4 or later |
+| Module format | ESM only                                                   |
+| Gatepost spec | 0.3.0                                                      |
+
+</div>
+
+A server can import the package. It defines the element only in a browser.
+
+## Next steps
+
+- [Use the field in React](../react/).
+- [Read the field spec](../../spec/field/), which defines the settings, the events and the states.
+- [Read the API reference of `@gatepost/field`](../../reference/js/field/).
diff --git a/src/content/docs/guides/react.md b/src/content/docs/guides/react.md
new file mode 100644
index 0000000..b259dde
--- /dev/null
+++ b/src/content/docs/guides/react.md
@@ -0,0 +1,84 @@
+---
+title: Add a postcode field to a React form
+description: Use the PostcodeField component of @gatepost/react in React 18 or 19, and in Next.js.
+sidebar:
+  label: React
+  order: 5
+---
+
+`@gatepost/react` wraps the field of `@gatepost/field` in a React component. It works with React 18 and React 19. It renders on the server, and a plain form sends the postcode in its canonical form.
+
+## Install
+
+The first alpha is not published yet. This page will say when it is.
+
+```sh
+pnpm add @gatepost/react
+```
+
+The package installs `@gatepost/field`, the custom element that does the work.
+
+## Add the field
+
+```tsx
+'use client';
+import { useState, type ReactElement } from 'react';
+import { PostcodeField } from '@gatepost/react';
+
+export function AddressForm(): ReactElement {
+  const [postcode, setPostcode] = useState('');
+  return (
+    <form action="/address">
+      <PostcodeField
+        name="postcode"
+        required
+        onChange={(detail) => {
+          setPostcode(detail.value);
+        }}
+      />
+      <p>{postcode}</p>
+      <button>Continue</button>
+    </form>
+  );
+}
+```
+
+A user who types `fc 01 z99 zz 01` sees `FC-01-Z99-ZZ-01`, and the form sends `postcode=FC-01-Z99-ZZ-01`.
+
+The module starts with `'use client'`, so the component works in the App Router of Next.js. The HTML of a server render already holds the settings of the field.
+
+## Choose the props
+
+<div class="table-scroll" role="region" tabindex="0" aria-label="Table: Props of PostcodeField">
+
+| Prop                                           | Meaning                                                               |
+| ---------------------------------------------- | --------------------------------------------------------------------- |
+| `name`, `defaultValue`, `required`, `disabled` | as for a native input                                                 |
+| `label`                                        | the visible label. The default is `Postcode`                          |
+| `apiKey`                                       | a publishable key. Without one, the field sends no request            |
+| `baseUrl`                                      | the gateway's address                                                 |
+| `confirm`                                      | `none`, `level1` or `level2`. The default is `level1`                 |
+| `gps`                                          | true shows the location button, when the field has a key              |
+| `legacy`                                       | `accept` or `reject` an old 6-digit postcode. The default is `accept` |
+| `messages`                                     | text that replaces the English messages, by key                       |
+
+</div>
+
+`onChange`, `onConfirm` and `onError` receive the detail of each event of the field. The `ref` gives the element, for `checkValidity()` and the other members of a form control.
+
+## Read the value
+
+The field keeps its own text, as an uncontrolled input does. `defaultValue` sets the text at first, and a form reset returns to it. A new `defaultValue` later changes that first text, and never the text that the user typed.
+
+Read each new value in `onChange`, or read the form when it submits. On React 19, a field that the browser rendered, not hydrated, keeps its first `defaultValue` after a later change of the prop. Set a `key` on the component if you need a new first text.
+
+The [HTML field guide](../html/) explains the key, the events, the messages and the theme tokens.
+
+## Requirements
+
+React 18 or 19. The browser needs are those of `@gatepost/field`. The package is ESM only, and it implements Gatepost spec 0.3.0.
+
+## Next steps
+
+- [Use the field without React](../html/).
+- [Read the API reference of `@gatepost/react`](../../reference/js/react/).
diff --git a/src/content/docs/start.md b/src/content/docs/start.md
index 56cb7dc..0767886 100644
--- a/src/content/docs/start.md
+++ b/src/content/docs/start.md
@@ -10,6 +10,8 @@ Each Gatepost tool follows the same spec, so each one reads a postcode in the sa
 | You want to                                              | Use                                                | Needs a key      |
 | -------------------------------------------------------- | -------------------------------------------------- | ---------------- |
 | Check the form of a postcode in TypeScript or JavaScript | [`@gatepost/core`](../guides/typescript/)          | no               |
+| Add a postcode field to an HTML form                     | [`@gatepost/field`](../guides/html/)               | only to confirm  |
+| Add a postcode field to a React form                     | [`@gatepost/react`](../guides/react/)              | only to confirm  |
 | Look up a postcode from a TypeScript server              | [`@gatepost/client`](../guides/typescript-client/) | yes              |
 | Check or look up a postcode in PHP                       | [`gatepost/postcode`](../guides/php/)              | only for lookups |
 
diff --git a/test/browser/field-examples.spec.ts b/test/browser/field-examples.spec.ts
new file mode 100644
index 0000000..0805266
--- /dev/null
+++ b/test/browser/field-examples.spec.ts
@@ -0,0 +1,86 @@
+// SPDX-FileCopyrightText: 2026 The Gatepost authors
+// SPDX-License-Identifier: Apache-2.0
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { startMockServer, type MockServer } from '@gatepost/mock-server';
+import { expect, test } from '@playwright/test';
+import { pageExamples } from '../support/examples.ts';
+
+// The field runs in a browser, so each HTML example of a guide loads here against the built
+// element. The CDN address of the example gets the file of the package, and the gateway gets the
+// mock gateway. Any other request stops the test, so nothing reaches NIPOST or another host.
+const CDN = 'https://cdn.jsdelivr.net/npm/@gatepost/field/dist/element.js';
+const GATEWAY = 'https://api.postcode.gov.ng/**';
+const ELEMENT = fileURLToPath(new URL('../../js/packages/field/dist/element.js', import.meta.url));
+const ORIGIN = 'http://localhost:3000';
+const MOCK_KEY = 'nipost_pk_test_mock';
+
+const EXAMPLES = pageExamples().filter(
+  ({ language, attributes, source }) =>
+    language === 'html' && attributes === '' && source.includes('<gatepost-postcode-field'),
+);
+
+let mock: MockServer;
+
+test.beforeAll(async () => {
+  mock = await startMockServer({ port: 0 });
+});
+
+test.afterAll(async () => {
+  await mock.close();
+});
+
+test('the guides hold HTML examples of the field, and the built element exists', () => {
+  expect(EXAMPLES.length).toBeGreaterThan(0);
+  expect(existsSync(ELEMENT), 'run pnpm sdk to build the field').toBe(true);
+});
+
+for (const { page: path, index, source } of EXAMPLES) {
+  test(`${path} block ${String(index)} defines the field and gives it a form value`, async ({
+    page,
+    context,
+  }) => {
+    const stray: string[] = [];
+    // The first route is the last to run: it stops every request that no other route handles.
+    await context.route('**/*', async (route) => {
+      const url = route.request().url();
+      if (url.startsWith(`${ORIGIN}/`) || url.startsWith(`${mock.url}/`)) {
+        await route.fallback();
+        return;
+      }
+      stray.push(url);
+      await route.abort();
+    });
+    await context.route(CDN, (route) =>
+      route.fulfill({ path: ELEMENT, contentType: 'text/javascript' }),
+    );
+    await context.route(GATEWAY, async (route) => {
+      const url = new URL(route.request().url());
+      const headers = { ...route.request().headers(), 'x-api-key': MOCK_KEY };
+      const response = await route.fetch({
+        url: `${mock.url}${url.pathname}${url.search}`,
+        headers,
+      });
+      await route.fulfill({ response });
+    });
+    await context.route(`${ORIGIN}/example`, (route) =>
+      route.fulfill({
+        contentType: 'text/html',
+        body: `<!doctype html><html lang="en-GB"><title>Example</title><main>${source}</main>`,
+      }),
+    );
+    await page.goto(`${ORIGIN}/example`);
+    await page.waitForFunction(() => customElements.get('gatepost-postcode-field') !== undefined);
+    await page.locator('gatepost-postcode-field input').fill('fc 01 z99 zz 01');
+    const field = page.locator('gatepost-postcode-field');
+    expect(await field.evaluate((element) => (element as HTMLInputElement).value)).toBe(
+      'FC-01-Z99-ZZ-01',
+    );
+    const sent = await field.evaluate((element) => {
+      const form = (element as HTMLInputElement).form;
+      return form === null ? null : new FormData(form).get('postcode');
+    });
+    if (source.includes('<form')) expect(sent).toBe('FC-01-Z99-ZZ-01');
+    expect(stray, 'requests to other hosts').toEqual([]);
+  });
+}
diff --git a/test/site/reference.test.ts b/test/site/reference.test.ts
index d79f850..d1f29f8 100644
--- a/test/site/reference.test.ts
+++ b/test/site/reference.test.ts
@@ -12,7 +12,7 @@ function reported(name: string): readonly ReportedExport[] {
   return exportsOf(readFileSync(`js/packages/${name}/etc/${name}.api.md`, 'utf8'));
 }
 
-describe.each(['core', 'client'])('the API reference of @gatepost/%s', (name) => {
+describe.each(['core', 'client', 'field', 'react'])('the API reference of @gatepost/%s', (name) => {
   it('has a page for each symbol of the API report', () => {
     const missing = reported(name)
       .map(
diff --git a/test/support/examples.ts b/test/support/examples.ts
index 5eb2a06..6284fdc 100644
--- a/test/support/examples.ts
+++ b/test/support/examples.ts
@@ -289,7 +289,7 @@ export function problemsOf(example: Example): readonly string[] {
   if (!closed) problems.push('The fence has no closing fence.');
   if (attributes !== '')
     problems.push(`The fence has the text "${attributes}" after the language.`);
-  if (!['ts', 'php', 'sh'].includes(language)) {
+  if (!['ts', 'php', 'sh', 'html', 'tsx', 'css'].includes(language)) {
     problems.push(`No check runs a block in the language "${language}".`);
   }
   if (language === 'ts') {
diff --git a/test/unit/examples.test.ts b/test/unit/examples.test.ts
index a704147..ac22d5a 100644
--- a/test/unit/examples.test.ts
+++ b/test/unit/examples.test.ts
@@ -39,7 +39,7 @@ function readJson(path: string): unknown {
 
 // The packages that an install command on a page may name: the Gatepost packages, and the HTTP
 // client that the PHP package tests with.
-const PNPM_PACKAGES = ['core', 'client'].map(
+const PNPM_PACKAGES = ['core', 'client', 'field', 'react'].map(
   (name) => (readJson(`js/packages/${name}/package.json`) as { name: string }).name,
 );
 const PHP_MANIFEST = readJson('php/composer.json') as {
@@ -129,6 +129,10 @@ describe('problemsOf', () => {
     expect(problemsOf(block('sh', 'pnpm add x\n'))).toEqual([]);
   });
 
+  it.each(['html', 'tsx', 'css'])('accepts a %s block, which a browser check runs', (language) => {
+    expect(problemsOf(block(language, 'x\n'))).toEqual([]);
+  });
+
   it('fails a PHP line that shows a result with no output to compare', () => {
     expect(problemsOf(block('php', '$r->valid; // true\n'))).toHaveLength(1);
     expect(problemsOf(block('php', 'var_dump($r->valid); // bool(true)\n'))).toHaveLength(1);
@@ -350,6 +354,31 @@ describe('every install command on a page', () => {
   });
 });
 
+// The field and the React wrapper run in a browser, so the js repo runs their README examples in
+// its own CI. A page may show only those examples, word for word. The browser tests of this repo
+// also load each HTML example against the built element.
+const README_EXAMPLES = ['field', 'react'].flatMap((name) =>
+  examplesOf(name, readFileSync(join(ROOT, `js/packages/${name}/README.md`), 'utf8')),
+);
+
+describe('every HTML, TSX and CSS example on a page', () => {
+  it('exists for the field and for React, so the check below cannot pass on none', () => {
+    expect(inLanguage('html').length).toBeGreaterThan(0);
+    expect(inLanguage('tsx').length).toBeGreaterThan(0);
+    expect(inLanguage('css').length).toBeGreaterThan(0);
+  });
+
+  it.each([...inLanguage('html'), ...inLanguage('tsx'), ...inLanguage('css')])(
+    'is a README example that the CI of the js repo runs: %s',
+    (_, { language, source }) => {
+      const sources = README_EXAMPLES.filter((example) => example.language === language).map(
+        (example) => example.source,
+      );
+      expect(sources).toContain(source);
+    },
+  );
+});
+
 describe('every example on a page', () => {
   let mock: MockServer;
   let folder: string;
diff --git a/test/unit/release-state.test.ts b/test/unit/release-state.test.ts
index c567f6f..9fdd337 100644
--- a/test/unit/release-state.test.ts
+++ b/test/unit/release-state.test.ts
@@ -28,7 +28,7 @@ describe('the release state', () => {
   });
 
   it('has guides with an install command, so the checks below cannot pass on no page', () => {
-    expect(INSTALL_PAGES.length).toBeGreaterThanOrEqual(3);
+    expect(INSTALL_PAGES.length).toBeGreaterThanOrEqual(5);
   });
 
   it.each(INSTALL_PAGES)('matches the install notice of %s', (page) => {
diff --git a/test/unit/spec-pages.test.ts b/test/unit/spec-pages.test.ts
index bf5518c..2a3eb91 100644
--- a/test/unit/spec-pages.test.ts
+++ b/test/unit/spec-pages.test.ts
@@ -10,8 +10,8 @@ const SPEC_VERSION = readFileSync('spec/VERSION', 'utf8').trim();
 const PAGES = specPages('spec', 'abc123');
 
 describe('specPages', () => {
-  it('builds the grammar, the client contract and the glossary', () => {
-    expect(PAGES.map(({ slug }) => slug)).toEqual(['grammar', 'client', 'glossary']);
+  it('builds the grammar, the client contract, the field and the glossary', () => {
+    expect(PAGES.map(({ slug }) => slug)).toEqual(['grammar', 'client', 'field', 'glossary']);
   });
 
   it('gives each page a title and drops the first heading of its file', () => {

From f0b9adb5044ed9521e66be99379bbdf35a1283e8 Mon Sep 17 00:00:00 2001
From: MobileMage <aidelojejoshua@gmail.com>
Date: Sun, 4 Oct 2026 02:14:37 +0100
Subject: [PATCH 3/4] docs: check the field guides against the built packages

The TSX example and the tables of props, attributes and events could
drift from the packages while every test stayed green. A test now
type-checks each TSX block against the built React types. Other tests
compare each table with the API report of the React package and with
the field spec. The HTML guide no longer repeats a claim about the
release state, it names the key that the location button needs, and
the README and a comment list the field page.

Signed-off-by: MobileMage <aidelojejoshua@gmail.com>
---
 README.md                       |   4 +-
 scripts/spec-pages.ts           |   2 +-
 src/content/docs/guides/html.md |   4 +-
 test/unit/examples.test.ts      | 102 +++++++++++++++++++++++++++++++-
 4 files changed, 106 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index edfa6db..41a8597 100644
--- a/README.md
+++ b/README.md
@@ -27,9 +27,9 @@ This repo holds the source of the site at <https://gatepost-dev.github.io/docs/>
 ## What the site holds
 
 - A [playground](https://gatepost-dev.github.io/docs/playground/) where you check a postcode in your browser.
-- Guides for the TypeScript core, the TypeScript client and the PHP package.
+- Guides for the TypeScript core, the TypeScript client, the PHP package, the HTML field and the React field.
 - An API reference that the build writes from the TSDoc comments and the PHP doc comments.
-- The spec pages: the grammar, the client contract and the glossary.
+- The spec pages: the grammar, the client contract, the field and the glossary.
 - A [readiness tracker](https://gatepost-dev.github.io/docs/readiness/) of common tools that reject the new postcode.
 
 ## Run it on your computer
diff --git a/scripts/spec-pages.ts b/scripts/spec-pages.ts
index 0726596..e7b7c28 100644
--- a/scripts/spec-pages.ts
+++ b/scripts/spec-pages.ts
@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: 2026 The Gatepost authors
 // SPDX-License-Identifier: Apache-2.0
 // Writes the spec pages of the site from the spec submodule, so that the site shows the grammar,
-// the client contract and the glossary that the SDKs implement, word for word.
+// the client contract, the field and the glossary that the SDKs implement, word for word.
 import { execFileSync } from 'node:child_process';
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
diff --git a/src/content/docs/guides/html.md b/src/content/docs/guides/html.md
index 3851c90..d0e79b9 100644
--- a/src/content/docs/guides/html.md
+++ b/src/content/docs/guides/html.md
@@ -16,7 +16,7 @@ The first alpha is not published yet. This page will say when it is.
 pnpm add @gatepost/field
 ```
 
-Until the release, the CDN address in the examples below does not work. Import `@gatepost/field` once in your app, and the page can use the element. A page with no build step can load the one-file build from a CDN instead. After a release exists, pin its version in the CDN address of a production page.
+Import `@gatepost/field` once in your app, and the page can use the element. A page with no build step can load the one-file build from a CDN instead, as the examples below do. Pin a version in the CDN address of a production page.
 
 ## Add the field
 
@@ -63,7 +63,7 @@ A key holds a lookup level, and a call above it fails. The field then says that
 
 </div>
 
-With `gps`, a button puts the postcode of the user's location in the input. The field asks for the location only when the user presses the button. With `legacy="accept"`, the field also accepts an old 6-digit postcode.
+With `gps` and a key that the field accepts, a button puts the postcode of the user's location in the input. The field asks for the location only when the user presses the button. A location that is not precise enough gives a partial postcode, and the user types the rest. With `legacy="accept"`, the field also accepts an old 6-digit postcode.
 
 ## Listen for changes
 
diff --git a/test/unit/examples.test.ts b/test/unit/examples.test.ts
index ac22d5a..c209fc2 100644
--- a/test/unit/examples.test.ts
+++ b/test/unit/examples.test.ts
@@ -129,7 +129,8 @@ describe('problemsOf', () => {
     expect(problemsOf(block('sh', 'pnpm add x\n'))).toEqual([]);
   });
 
-  it.each(['html', 'tsx', 'css'])('accepts a %s block, which a browser check runs', (language) => {
+  // The js repo runs these blocks in a browser. The README check below ties each page block to one.
+  it.each(['html', 'tsx', 'css'])('accepts a %s block, which the js repo runs', (language) => {
     expect(problemsOf(block(language, 'x\n'))).toEqual([]);
   });
 
@@ -379,6 +380,67 @@ describe('every HTML, TSX and CSS example on a page', () => {
   );
 });
 
+// The rows of the first table in the lines, without its header and its divider.
+function rowsOf(lines: readonly string[]): readonly string[] {
+  const start = lines.findIndex((line) => line.startsWith('|'));
+  if (start < 0) return [];
+  const rest = lines.slice(start);
+  const end = rest.findIndex((line) => !line.startsWith('|'));
+  return (end < 0 ? rest : rest.slice(0, end)).slice(2);
+}
+
+// The names in a table of a guide. The first column of the table that follows the box with the
+// label holds them, each between backticks.
+function tableNames(page: string, label: string): readonly string[] {
+  const text = readFileSync(join(ROOT, `src/content/docs/guides/${page}.md`), 'utf8');
+  const after = text.split(`aria-label="Table: ${label}">`)[1];
+  if (after === undefined) throw new Error(`${page}.md has no table "${label}".`);
+  const rows = rowsOf(after.split('\n'));
+  return rows.flatMap((row) =>
+    Array.from((row.split('|')[1] ?? '').matchAll(/`([^`]+)`/g), ([, name]) => name ?? ''),
+  );
+}
+
+const SPEC_FIELD = readFileSync(join(ROOT, 'spec/field.md'), 'utf8');
+const sorted = (names: readonly string[]): readonly string[] => [...names].sort();
+
+describe('the names in the tables of the field guides', () => {
+  it('lists the attributes that spec/field.md names', () => {
+    const line = SPEC_FIELD.split('\n').find((text) => text.includes('in kebab-case:')) ?? '';
+    const spec = Array.from(
+      line
+        .split('kebab-case:')[1]
+        ?.split('. ')[0]
+        ?.matchAll(/`([^`]+)`/g) ?? [],
+      ([, n]) => n ?? '',
+    );
+    expect(spec.length).toBeGreaterThan(5);
+    expect(sorted(tableNames('html', 'Attributes of the field'))).toEqual(sorted(spec));
+  });
+
+  it('lists the events that spec/field.md names, with the prefix of the web field', () => {
+    const rows = rowsOf((SPEC_FIELD.split('### Events\n')[1] ?? '').split('\n'));
+    const spec = rows.map(
+      (row) => `gatepost-${(row.split('|')[1] ?? '').replaceAll('`', '').trim()}`,
+    );
+    expect(spec).toHaveLength(3);
+    expect(sorted(tableNames('html', 'Events of the field'))).toEqual(sorted(spec));
+  });
+
+  it('lists the props of PostcodeFieldProps in the API report, and names each handler', () => {
+    const report = readFileSync(join(ROOT, 'js/packages/react/etc/react.api.md'), 'utf8');
+    const body = report.split('export interface PostcodeFieldProps {')[1]?.split('\n}')[0] ?? '';
+    const members = Array.from(body.matchAll(/^\s+readonly (\w+)\??:/gm), ([, name]) => name ?? '');
+    expect(members).toContain('apiKey');
+    const handlers = members.filter((name) => /^on[A-Z]/.test(name));
+    const guide = readFileSync(join(ROOT, 'src/content/docs/guides/react.md'), 'utf8');
+    expect(handlers.length).toBeGreaterThan(0);
+    for (const handler of handlers) expect(guide).toContain(`\`${handler}\``);
+    const props = members.filter((name) => !handlers.includes(name));
+    expect(sorted(tableNames('react', 'Props of PostcodeField'))).toEqual(sorted(props));
+  });
+});
+
 describe('every example on a page', () => {
   let mock: MockServer;
   let folder: string;
@@ -416,6 +478,44 @@ describe('every example on a page', () => {
     expect(problems).toBe('');
   });
 
+  // The block imports the built package, so a renamed prop fails here, whatever the README says.
+  it(
+    'type-checks every TSX example against the built @gatepost/react',
+    { timeout: 120_000 },
+    async () => {
+      const react = join(ROOT, 'js/packages/react');
+      const types = join(react, 'node_modules/@types/react');
+      for (const [name, { source }] of inLanguage('tsx')) {
+        writeFileSync(join(folder, `${name.replace(/\W+/g, '-')}.tsx`), source);
+      }
+      writeFileSync(
+        join(folder, 'tsconfig.tsx.json'),
+        JSON.stringify({
+          extends: join(ROOT, 'tsconfig.json'),
+          compilerOptions: {
+            jsx: 'react-jsx',
+            lib: ['ES2022', 'DOM', 'DOM.Iterable'],
+            paths: {
+              '@gatepost/react': [join(react, 'dist/index.d.ts')],
+              react: [join(types, 'index.d.ts')],
+              'react/*': [join(types, '*')],
+            },
+          },
+          include: ['*.tsx'],
+        }),
+      );
+      const tsc = join(ROOT, 'node_modules/typescript/bin/tsc');
+      let problems = '';
+      try {
+        await run(process.execPath, [tsc, '--noEmit', '-p', join(folder, 'tsconfig.tsx.json')]);
+      } catch (error) {
+        problems =
+          error instanceof Error && 'stdout' in error ? String(error.stdout) : String(error);
+      }
+      expect(problems).toBe('');
+    },
+  );
+
   it.each(inLanguage('ts'))('runs and shows only true results: %s', async (name, { source }) => {
     const file = moduleOf(name);
     writeFileSync(file, toCheckedModule(source, MODULES));

From ac1faf15ddd9570df9d5caa4fa7a3aa5271832ef Mon Sep 17 00:00:00 2001
From: MobileMage <aidelojejoshua@gmail.com>
Date: Sun, 4 Oct 2026 02:25:13 +0100
Subject: [PATCH 4/4] chore: pin the php submodule to its spec 0.3.0 commit

The PHP package now implements spec 0.3.0, as the TypeScript packages
do, so the test that every SDK of the site implements one spec version
passes again.

Signed-off-by: MobileMage <aidelojejoshua@gmail.com>
---
 php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/php b/php
index 831f332..a1dd163 160000
--- a/php
+++ b/php
@@ -1 +1 @@
-Subproject commit 831f332f5f6441cd051094e3a5a09843978c9f51
+Subproject commit a1dd1633c7f908ae3a24f12e2bfcd214e7191953