From e27e3839df0f60517ebab713273cece156020a95 Mon Sep 17 00:00:00 2001
From: James Loveridge <james.loveridge@ft.com>
Date: Thu, 27 Nov 2025 10:05:32 +0000
Subject: [PATCH 01/22] feat: add functionality for Constraint Validation API &
 types

---
 components/o3-form/src/js/validation.js      | 368 +++++++++++++++++++
 components/o3-form/src/types/validation.d.ts |  53 +++
 2 files changed, 421 insertions(+)
 create mode 100644 components/o3-form/src/js/validation.js
 create mode 100644 components/o3-form/src/types/validation.d.ts

diff --git a/components/o3-form/src/js/validation.js b/components/o3-form/src/js/validation.js
new file mode 100644
index 0000000000..88b48116df
--- /dev/null
+++ b/components/o3-form/src/js/validation.js
@@ -0,0 +1,368 @@
+/**
+ * Options to configure validation behaviour.
+ *
+ * @typedef {Object} O3ValidationOptions
+ * @property {boolean} [useBrowserReport=false] When true, call `form.reportValidity()` after an invalid submit (do not combine with `preventSubmit=true`).
+ * @property {boolean} [errorSummary=true] Whether to create/update an error summary element.
+ * @property {Object.<string,string>} [customMessages] Map of field id or name to a custom error message override.
+ * @property {boolean} [preventSubmit=true] Prevent form submission while invalid.
+ * @property {boolean} [focusFirstInvalid=true] Focus the first invalid control (or summary heading) after validation.
+ * @property {(formEl: HTMLFormElement) => Promise<FieldError[]>} [asyncValidate] Optional future hook for asynchronous validation. (Reserved; currently ignored.)
+ */
+
+/**
+ * FieldError represents a single invalid field.
+ * Mirrors exported TS FieldError type.
+ *
+ * @typedef {Object} FieldError
+ * @property {string} id Element id (may be blank if missing; summary links omitted if so).
+ * @property {string} fieldName Human friendly label text.
+ * @property {string} message Validation message.
+ * @property {('native'|'custom')} [source] Origin of message (native browser vs custom override).
+ */
+
+const SUMMARY_SELECTOR = '.o3-form__error-summary';
+const SUMMARY_CLASS = 'o3-form__error-summary';
+const ERROR_INPUT_CLASS = 'o3-form-text-input--error';
+const ERROR_CHECK_CLASS = 'o3-form-input-error';
+
+/** Maintain internal state per form element */
+const formState = new WeakMap();
+
+/**
+ * Derive a human readable field name from its associated `<label>` or fallback attributes.
+ *
+ * @param {HTMLInputElement|HTMLSelectElement|HTMLTextAreaElement} element The form control to derive a label for.
+ * @returns {string} A human friendly name for the field.
+ */
+function deriveFieldName(element) {
+	if (!element) return 'Field';
+	if (element.id) {
+		const label = element.form?.querySelector(`label[for="${element.id}"]`);
+		if (label && label.textContent) return label.textContent.trim();
+	}
+	return element.getAttribute('name') || element.id || 'Field';
+}
+
+/**
+ * Collect invalid fields using the Constraint Validation API.
+ *
+ * @param {HTMLFormElement} formElement The form to scan for invalid controls.
+ * @param {O3ValidationOptions} validationOptions Validation configuration.
+ * @returns {FieldError[]} An array of field error objects.
+ */
+function collectInvalidFields(formElement, validationOptions) {
+	const elements = Array.from(formElement.elements);
+	/** @type {FieldError[]} */
+	const errors = [];
+	for (const fieldElement of elements) {
+		if (
+			!(
+				fieldElement instanceof HTMLInputElement ||
+				fieldElement instanceof HTMLSelectElement ||
+				fieldElement instanceof HTMLTextAreaElement
+			)
+		)
+			continue;
+		if (fieldElement.checkValidity()) continue;
+		let message = fieldElement.validationMessage;
+		let source = 'native';
+		// Custom message precedence: explicit option map -> data attributes
+		const idOrName = fieldElement.id || fieldElement.name;
+		if (
+			idOrName &&
+			validationOptions.customMessages &&
+			validationOptions.customMessages[idOrName]
+		) {
+			message = validationOptions.customMessages[idOrName];
+			source = 'custom';
+		} else {
+			// Data attribute overrides (e.g. data-o3-form-message-required)
+			const validity = fieldElement.validity;
+			const dataKey = validity.valueMissing
+				? 'required'
+				: validity.typeMismatch
+				? 'type'
+				: validity.patternMismatch
+				? 'pattern'
+				: validity.tooShort
+				? 'too-short'
+				: validity.tooLong
+				? 'too-long'
+				: validity.rangeUnderflow
+				? 'range-underflow'
+				: validity.rangeOverflow
+				? 'range-overflow'
+				: validity.stepMismatch
+				? 'step'
+				: validity.badInput
+				? 'bad-input'
+				: null;
+			if (dataKey) {
+				const attr = fieldElement.getAttribute(
+					`data-o3-form-message-${dataKey}`
+				);
+				if (attr) {
+					message = attr;
+					source = 'custom';
+				}
+			}
+		}
+		errors.push({
+			id: fieldElement.id,
+			fieldName: deriveFieldName(fieldElement),
+			message,
+			source,
+		});
+	}
+	return errors;
+}
+
+/**
+ * Apply or remove inline error classes on affected form controls.
+ *
+ * @param {HTMLFormElement} formElement The form element hosting the controls.
+ * @param {FieldError[]} errors Current list of errors to reflect.
+ */
+function applyInlineFeedback(formElement, errors) {
+	const invalidIds = new Set(errors.map(error => error.id));
+	const elements = Array.from(formElement.elements);
+	for (const fieldElement of elements) {
+		if (!(fieldElement instanceof HTMLElement)) continue;
+		const isInvalid = fieldElement.id && invalidIds.has(fieldElement.id);
+		if (fieldElement.classList.contains('o3-form-text-input')) {
+			fieldElement.classList.toggle(ERROR_INPUT_CLASS, isInvalid);
+		}
+		if (
+			fieldElement.classList.contains('o3-form-input-radio-button') ||
+			fieldElement.classList.contains('o3-form-input-checkbox__input')
+		) {
+			fieldElement.classList.toggle(ERROR_CHECK_CLASS, isInvalid);
+		}
+	}
+}
+
+/**
+ * Render or update the error summary element for the form.
+ *
+ * @param {HTMLFormElement} formElement The form to render a summary for.
+ * @param {FieldError[]} errors Errors to list; if empty the summary is removed.
+ * @param {O3ValidationOptions} validationOptions Validation configuration.
+ */
+function renderErrorSummary(formElement, errors, validationOptions) {
+	if (!validationOptions.errorSummary) return;
+	let summary = formElement.querySelector(SUMMARY_SELECTOR);
+	if (!errors.length) {
+		if (summary) summary.remove();
+		return;
+	}
+	if (!summary) {
+		summary = document.createElement('div');
+		summary.className = SUMMARY_CLASS;
+		summary.setAttribute('role', 'alert');
+		summary.setAttribute('aria-live', 'polite');
+		formElement.insertBefore(summary, formElement.firstChild);
+	}
+	summary.innerHTML = '';
+	const icon = document.createElement('span');
+	icon.className = 'o3-form__error-summary-icon';
+	const headingWrapper = document.createElement('div');
+	headingWrapper.className = 'o3-form__error-summary__heading';
+	headingWrapper.setAttribute('aria-labelledby', 'error-summary-title');
+	const heading = document.createElement('span');
+	heading.id = 'error-summary-title';
+	heading.className = 'o3-typography-heading5';
+	heading.textContent = 'Please correct these errors and try again.';
+	const list = document.createElement('ul');
+	list.className = 'o3-forms__error-summary__list o3-typography-body-small';
+	for (const error of errors) {
+		const listItem = document.createElement('li');
+		if (error.id) {
+			const link = document.createElement('a');
+			link.className = 'o3-typography-link';
+			link.href = `#${error.id}`;
+			link.textContent = error.fieldName;
+			listItem.appendChild(link);
+			const messageSpan = document.createElement('span');
+			messageSpan.textContent = `: ${error.message}`;
+			listItem.appendChild(messageSpan);
+		} else {
+			listItem.textContent = `${error.fieldName}: ${error.message}`;
+		}
+		list.appendChild(listItem);
+	}
+	headingWrapper.appendChild(heading);
+	headingWrapper.appendChild(list);
+	summary.appendChild(icon);
+	summary.appendChild(headingWrapper);
+	if (validationOptions.focusFirstInvalid) {
+		heading.focus?.();
+	}
+}
+
+/**
+ * Revalidate a single field and update inline feedback (does not rebuild summary).
+ *
+ * @param {HTMLElement} element The field to revalidate.
+ * @param {O3ValidationOptions} validationOptions Validation configuration.
+ * @returns {FieldError|null} A field error if invalid, otherwise null.
+ */
+function revalidateField(element, validationOptions) {
+	if (
+		!(
+			element instanceof HTMLInputElement ||
+			element instanceof HTMLSelectElement ||
+			element instanceof HTMLTextAreaElement
+		)
+	) {
+		return null;
+	}
+	if (element.checkValidity()) {
+		// clear custom validity if previously set
+		element.setCustomValidity('');
+		if (element.classList.contains('o3-form-text-input')) {
+			element.classList.remove(ERROR_INPUT_CLASS);
+		}
+		if (
+			element.classList.contains('o3-form-input-radio-button') ||
+			element.classList.contains('o3-form-input-checkbox__input')
+		) {
+			element.classList.remove(ERROR_CHECK_CLASS);
+		}
+		return null;
+	}
+	const [error] = collectInvalidFields(element.form, validationOptions).filter(
+		e => e.id === element.id
+	);
+	if (error) {
+		if (element.classList.contains('o3-form-text-input'))
+			element.classList.add(ERROR_INPUT_CLASS);
+		if (
+			element.classList.contains('o3-form-input-radio-button') ||
+			element.classList.contains('o3-form-input-checkbox__input')
+		)
+			element.classList.add(ERROR_CHECK_CLASS);
+		return error;
+	}
+	return null;
+}
+
+/**
+ * Set a custom message for a field; clears any previous message when falsy.
+ *
+ * @param {HTMLInputElement|HTMLSelectElement|HTMLTextAreaElement} element The field element to annotate.
+ * @param {string} message The custom message (empty string clears).
+ */
+function setCustomMessage(element, message) {
+	if (!element) return;
+	element.setCustomValidity(message || '');
+}
+
+/**
+ * Initialise validation on a form element or selector.
+ *
+ * @param {string|HTMLFormElement} formOrSelector A form element or a selector resolving to one.
+ * @param {O3ValidationOptions} [options] Validation configuration overrides.
+ * @returns {HTMLFormElement|null} The initialised form element.
+ */
+function initO3FormValidation(formOrSelector, options = {}) {
+	const formElement =
+		formOrSelector instanceof HTMLFormElement
+			? formOrSelector
+			: document.querySelector(formOrSelector);
+	if (!formElement || !(formElement instanceof HTMLFormElement)) {
+		throw new Error(
+			'initO3FormValidation must be passed a form element or selector resolving to a form.'
+		);
+	}
+	const validationOptions = Object.assign(
+		{
+			useBrowserReport: false,
+			errorSummary: true,
+			customMessages: undefined,
+			preventSubmit: true,
+			focusFirstInvalid: true,
+		},
+		options
+	);
+	if (validationOptions.useBrowserReport && validationOptions.preventSubmit) {
+		throw new Error('Cannot enable both useBrowserReport and preventSubmit.');
+	}
+	if (formState.has(formElement)) return formElement; // already initialised
+
+	const state = {validationOptions}; // future: may hold cached lastErrors etc.
+	formState.set(formElement, state);
+
+	formElement.addEventListener('submit', event => {
+		const current = formState.get(formElement);
+		if (!current) return;
+		const {validationOptions} = current;
+		const invalid = !formElement.checkValidity();
+		if (invalid) {
+			if (validationOptions.preventSubmit) event.preventDefault();
+			const errors = collectInvalidFields(formElement, validationOptions);
+			applyInlineFeedback(formElement, errors);
+			renderErrorSummary(formElement, errors, validationOptions);
+			if (errors.length && validationOptions.focusFirstInvalid) {
+				const target = formElement.querySelector(`#${errors[0].id}`);
+				target?.focus();
+			}
+			if (validationOptions.useBrowserReport) {
+				formElement.reportValidity();
+			}
+		}
+	});
+
+	// progressive revalidation
+	const progressiveHandler = event => {
+		const current = formState.get(formElement);
+		if (!current) return;
+		revalidateField(event.target, current.validationOptions);
+	};
+	formElement.addEventListener('input', progressiveHandler, true);
+	formElement.addEventListener('blur', progressiveHandler, true);
+	formElement.addEventListener(
+		'invalid',
+		event => {
+			// suppress native tooltip when using custom summary
+			const current = formState.get(formElement);
+			if (!current) return;
+			if (current.validationOptions.errorSummary) {
+				event.preventDefault();
+			}
+		},
+		true
+	);
+
+	return formElement;
+}
+
+/**
+ * Destroy validation instance: remove listeners and summary.
+ *
+ * @param {string|HTMLFormElement} formOrSelector A form element or a selector resolving to one.
+ */
+function destroyO3FormValidation(formOrSelector) {
+	const formElement =
+		formOrSelector instanceof HTMLFormElement
+			? formOrSelector
+			: document.querySelector(formOrSelector);
+	if (!formElement || !(formElement instanceof HTMLFormElement)) return;
+	const state = formState.get(formElement);
+	if (!state) return;
+	// clone without listeners (simpler than tracking each bound handler)
+	const clone = formElement.cloneNode(true);
+	formElement.parentNode?.replaceChild(clone, formElement);
+	const summary = clone.querySelector(SUMMARY_SELECTOR);
+	summary?.remove();
+	formState.delete(clone); // new clone not initialised
+}
+
+export {
+	collectInvalidFields,
+	destroyO3FormValidation,
+	initO3FormValidation,
+	revalidateField,
+	setCustomMessage,
+	renderErrorSummary as showErrorSummary,
+};
diff --git a/components/o3-form/src/types/validation.d.ts b/components/o3-form/src/types/validation.d.ts
new file mode 100644
index 0000000000..7c5199d841
--- /dev/null
+++ b/components/o3-form/src/types/validation.d.ts
@@ -0,0 +1,53 @@
+declare module '@financial-times/o3-form/validation' {
+	export type FieldError = {
+		id: string;
+		fieldName: string;
+		message: string;
+		source?: 'native' | 'custom';
+	};
+
+	export type O3ValidationOptions = {
+		useBrowserReport?: boolean;
+		errorSummary?: boolean;
+		customMessages?: Record<string, string>;
+		preventSubmit?: boolean;
+		focusFirstInvalid?: boolean;
+		asyncValidate?: (formEl: HTMLFormElement) => Promise<FieldError[]>; // reserved for future
+	};
+
+	/** Initialise validation on a form element or selector. */
+	export function initO3FormValidation(
+		formOrSelector: string | HTMLFormElement,
+		options?: O3ValidationOptions
+	): HTMLFormElement | null;
+
+	/** Tear down validation listeners and remove summary if present. */
+	export function destroyO3FormValidation(
+		formOrSelector: string | HTMLFormElement
+	): void;
+
+	/** Collect current invalid fields for a form element. */
+	export function collectInvalidFields(
+		formEl: HTMLFormElement,
+		opts: O3ValidationOptions
+	): FieldError[];
+
+	/** Show or update an error summary section. */
+	export function showErrorSummary(
+		formEl: HTMLFormElement,
+		errors: FieldError[],
+		opts: O3ValidationOptions
+	): void;
+
+	/** Set a custom validity message for a given field. */
+	export function setCustomMessage(
+		inputEl: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement,
+		message: string
+	): void;
+
+	/** Revalidate a single field and return its error or null. */
+	export function revalidateField(
+		inputEl: HTMLElement,
+		opts: O3ValidationOptions
+	): FieldError | null;
+}

From 65ad842328bc1182550a2689872fbdaf51771038 Mon Sep 17 00:00:00 2001
From: "ben.freshwater" <ben.freshwater@ft.com>
Date: Thu, 11 Dec 2025 10:57:45 +0000
Subject: [PATCH 02/22] chore: introduce formValidation story

---
 components/o3-form/src/js/validation.js       |   1 +
 .../o3-form/src/tsx/fieldComponents/Form.tsx  |   5 +-
 .../stories/formValidation.stories.tsx        | 131 ++++++++++++++++++
 3 files changed, 135 insertions(+), 2 deletions(-)
 create mode 100644 components/o3-form/stories/formValidation.stories.tsx

diff --git a/components/o3-form/src/js/validation.js b/components/o3-form/src/js/validation.js
index 88b48116df..3659ffead0 100644
--- a/components/o3-form/src/js/validation.js
+++ b/components/o3-form/src/js/validation.js
@@ -270,6 +270,7 @@ function initO3FormValidation(formOrSelector, options = {}) {
 		formOrSelector instanceof HTMLFormElement
 			? formOrSelector
 			: document.querySelector(formOrSelector);
+
 	if (!formElement || !(formElement instanceof HTMLFormElement)) {
 		throw new Error(
 			'initO3FormValidation must be passed a form element or selector resolving to a form.'
diff --git a/components/o3-form/src/tsx/fieldComponents/Form.tsx b/components/o3-form/src/tsx/fieldComponents/Form.tsx
index 0d08f24166..cf9c0df417 100644
--- a/components/o3-form/src/tsx/fieldComponents/Form.tsx
+++ b/components/o3-form/src/tsx/fieldComponents/Form.tsx
@@ -1,5 +1,6 @@
-export const Form = ({children}: {
+export const Form = ({id, children}: {
+	id?: string,
 	children: React.JSX.Element | React.JSX.Element[];
 }) => {
-	return <form className="o3-form">{children}</form>;
+	return <form id={id} className="o3-form" >{children}</form>;
 };
diff --git a/components/o3-form/stories/formValidation.stories.tsx b/components/o3-form/stories/formValidation.stories.tsx
new file mode 100644
index 0000000000..ac8942c80a
--- /dev/null
+++ b/components/o3-form/stories/formValidation.stories.tsx
@@ -0,0 +1,131 @@
+import type {Meta} from '@storybook/react';
+import links from '@financial-times/o3-figma-sb-links';
+
+import {Form as FormTsx} from '../src/tsx';
+
+import '../src/css/brands/core.css';
+import '../src/css/brands/professional.css';
+import '../src/css/brands/internal.css';
+import '../src/css/brands/whitelabel.css';
+import '../src/css/brands/sustainable-views.css';
+import { initO3FormValidation} from "../src/js/validation";
+
+const meta: Meta<typeof FormTsx> = {
+	title: 'o3-form',
+	component: FormTsx,
+	tags: [
+		'experimental',
+		'core',
+		'professional',
+		'internal',
+		'whitelabel',
+		'sustainable-views',
+	],
+	decorators: [
+		Story => (
+			<div data-o3-brand="core" className="o3-grid">
+				<div
+					style={{gridColumn: `content-start / content-end`}}>
+					<Story/>
+				</div>
+			</div>
+		),
+	],
+	parameters: {
+		backgrounds: {disable: true},
+	},
+} as Meta;
+
+export const FormValidation = {
+	parameters: {
+		design: {
+			type: 'figma',
+			url: links['whitelabel-o3-form--text-input'].figma,
+		},
+	},
+	render: args => {
+		return (
+			// Use HTML instead of TSX to replicate a real-world use case of validation.js
+			<form id="demo-form" className='demo-form'>
+				<div className="o3-form-field">
+					<label
+						className="o3-form-field__label"
+						htmlFor="o3-form-text-input-_9004070302523871"
+					>
+						First name
+					</label>
+					<span
+						className="o3-form-input__description"
+						id="o3-form-description_41273237907367455"
+					>
+          				The name you are referred to by
+        			</span>
+					<input
+						id="o3-form-text-input-_9004070302523871"
+						className="o3-form o3-form-text-input"
+						required
+						aria-required="true"
+						type="text"
+					/>
+				</div>
+				<div className="o3-form-field">
+					<label
+						className="o3-form-field__label"
+						htmlFor="o3-form-text-input-_3017971228893219"
+					>
+						Last name
+					</label>
+					<span
+						className="o3-form-input__description"
+						id="o3-form-description_9230638484727663"
+					>
+          				Your family name
+        			</span>
+					<input
+						id="o3-form-text-input-_3017971228893219"
+						className="o3-form o3-form-text-input"
+						required
+						aria-required="true"
+						type="text"
+					/>
+				</div>
+				<div className="o3-form-field">
+					<label
+						className="o3-form-field__label"
+						htmlFor="o3-form-text-input-_9285747170073946"
+					>
+						CVV code
+					</label>
+					<span
+						className="o3-form-input__description"
+						id="o3-form-description_03257263157199375"
+					>
+          				We're definitely not stealing your data
+        			</span>
+					<input
+						id="o3-form-text-input-_9285747170073946"
+						className="o3-form o3-form-text-input"
+						required
+						aria-required="true"
+						type="text"
+					/>
+				</div>
+				<button className="o3-button o3-button--primary" type="submit">Submit</button>
+			</form>
+		);
+	},
+	play: async ({ canvasElement }) => {
+		const form = canvasElement.querySelector(
+			'#demo-form'
+		) as HTMLFormElement | null;
+
+		console.log('[play] form from canvasElement:', form);
+
+		form.addEventListener('submit', e => console.log('[basic] submit fired', e));
+		if (form) {
+			initO3FormValidation(form);
+		}
+	},
+};
+
+export default meta;

From a94cd37fbe838c8ef35e4839f8b4e4de9515e0f8 Mon Sep 17 00:00:00 2001
From: "ben.freshwater" <ben.freshwater@ft.com>
Date: Wed, 7 Jan 2026 09:27:04 +0000
Subject: [PATCH 03/22] chore: introduce tests

---
 components/o3-form/src/js/validation.js       | 96 ++++++++++++------
 .../o3-form/stories/FormValidationHtml.tsx    | 70 +++++++++++++
 .../stories/formValidation.stories.tsx        | 78 +--------------
 .../stories/formValidation.test.stories.tsx   | 97 +++++++++++++++++++
 4 files changed, 240 insertions(+), 101 deletions(-)
 create mode 100644 components/o3-form/stories/FormValidationHtml.tsx
 create mode 100644 components/o3-form/stories/formValidation.test.stories.tsx

diff --git a/components/o3-form/src/js/validation.js b/components/o3-form/src/js/validation.js
index 3659ffead0..98cedf6185 100644
--- a/components/o3-form/src/js/validation.js
+++ b/components/o3-form/src/js/validation.js
@@ -44,6 +44,12 @@ function deriveFieldName(element) {
 	return element.getAttribute('name') || element.id || 'Field';
 }
 
+function isFormFieldElement(fieldElement) {
+	return fieldElement instanceof HTMLInputElement ||
+		fieldElement instanceof HTMLSelectElement ||
+		fieldElement instanceof HTMLTextAreaElement;
+}
+
 /**
  * Collect invalid fields using the Constraint Validation API.
  *
@@ -56,19 +62,18 @@ function collectInvalidFields(formElement, validationOptions) {
 	/** @type {FieldError[]} */
 	const errors = [];
 	for (const fieldElement of elements) {
-		if (
-			!(
-				fieldElement instanceof HTMLInputElement ||
-				fieldElement instanceof HTMLSelectElement ||
-				fieldElement instanceof HTMLTextAreaElement
-			)
-		)
+
+		if (!isFormFieldElement(fieldElement))
 			continue;
+
 		if (fieldElement.checkValidity()) continue;
+
 		let message = fieldElement.validationMessage;
 		let source = 'native';
+
 		// Custom message precedence: explicit option map -> data attributes
 		const idOrName = fieldElement.id || fieldElement.name;
+
 		if (
 			idOrName &&
 			validationOptions.customMessages &&
@@ -82,22 +87,22 @@ function collectInvalidFields(formElement, validationOptions) {
 			const dataKey = validity.valueMissing
 				? 'required'
 				: validity.typeMismatch
-				? 'type'
-				: validity.patternMismatch
-				? 'pattern'
-				: validity.tooShort
-				? 'too-short'
-				: validity.tooLong
-				? 'too-long'
-				: validity.rangeUnderflow
-				? 'range-underflow'
-				: validity.rangeOverflow
-				? 'range-overflow'
-				: validity.stepMismatch
-				? 'step'
-				: validity.badInput
-				? 'bad-input'
-				: null;
+					? 'type'
+					: validity.patternMismatch
+						? 'pattern'
+						: validity.tooShort
+							? 'too-short'
+							: validity.tooLong
+								? 'too-long'
+								: validity.rangeUnderflow
+									? 'range-underflow'
+									: validity.rangeOverflow
+										? 'range-overflow'
+										: validity.stepMismatch
+											? 'step'
+											: validity.badInput
+												? 'bad-input'
+												: null;
 			if (dataKey) {
 				const attr = fieldElement.getAttribute(
 					`data-o3-form-message-${dataKey}`
@@ -108,6 +113,7 @@ function collectInvalidFields(formElement, validationOptions) {
 				}
 			}
 		}
+
 		errors.push({
 			id: fieldElement.id,
 			fieldName: deriveFieldName(fieldElement),
@@ -129,13 +135,16 @@ function applyInlineFeedback(formElement, errors) {
 	const elements = Array.from(formElement.elements);
 	for (const fieldElement of elements) {
 		if (!(fieldElement instanceof HTMLElement)) continue;
+
 		const isInvalid = fieldElement.id && invalidIds.has(fieldElement.id);
-		if (fieldElement.classList.contains('o3-form-text-input')) {
+
+		if (fieldElement.classList.contains('o3-form-text-input') && !fieldElement.classList.contains(ERROR_INPUT_CLASS)) {
 			fieldElement.classList.toggle(ERROR_INPUT_CLASS, isInvalid);
 		}
+
 		if (
-			fieldElement.classList.contains('o3-form-input-radio-button') ||
-			fieldElement.classList.contains('o3-form-input-checkbox__input')
+			(fieldElement.classList.contains('o3-form-input-radio-button') ||
+				fieldElement.classList.contains('o3-form-input-checkbox__input')) && !fieldElement.clasList.contains(ERROR_CHECK_CLASS)
 		) {
 			fieldElement.classList.toggle(ERROR_CHECK_CLASS, isInvalid);
 		}
@@ -200,6 +209,22 @@ function renderErrorSummary(formElement, errors, validationOptions) {
 	}
 }
 
+/**
+ * Creates feedback element
+ *
+ * @param {Error} error The error to create a feedback element for.
+ * @returns {HTMLElement} A field error if invalid, otherwise null.
+ */
+function createFeedbackElement(error) {
+	const errorMessageContainer = document.createElement('div');
+	errorMessageContainer.classList.add('o3-form-feedback', 'o3-form-feedback__error');
+	const errorMessage = document.createElement('span');
+	errorMessage.classList.add('o3-form-feedback__error-message');
+	errorMessage.innerText = error.message;
+	errorMessageContainer.appendChild(errorMessage);
+	return errorMessageContainer;
+}
+
 /**
  * Revalidate a single field and update inline feedback (does not rebuild summary).
  *
@@ -217,26 +242,41 @@ function revalidateField(element, validationOptions) {
 	) {
 		return null;
 	}
+
 	if (element.checkValidity()) {
 		// clear custom validity if previously set
 		element.setCustomValidity('');
 		if (element.classList.contains('o3-form-text-input')) {
 			element.classList.remove(ERROR_INPUT_CLASS);
+			element.parentElement.querySelector('.o3-form-feedback__error')?.remove();
 		}
 		if (
 			element.classList.contains('o3-form-input-radio-button') ||
 			element.classList.contains('o3-form-input-checkbox__input')
 		) {
 			element.classList.remove(ERROR_CHECK_CLASS);
+			element.parentElement.querySelector('.o3-form-feedback__error')?.remove();
 		}
 		return null;
 	}
-	const [error] = collectInvalidFields(element.form, validationOptions).filter(
+
+	const errors = collectInvalidFields(element.form, validationOptions).filter(
 		e => e.id === element.id
 	);
+
+	applyInlineFeedback(element.form, errors);
+
+	const [error] = errors;
 	if (error) {
+		if (!element.parentElement.querySelector('.o3-form-feedback__error')) {
+			const errorMessageContainer = createFeedbackElement(error);
+			element.closest('.o3-form-field').appendChild(errorMessageContainer);
+		}
+
 		if (element.classList.contains('o3-form-text-input'))
 			element.classList.add(ERROR_INPUT_CLASS);
+
+
 		if (
 			element.classList.contains('o3-form-input-radio-button') ||
 			element.classList.contains('o3-form-input-checkbox__input')
@@ -303,6 +343,7 @@ function initO3FormValidation(formOrSelector, options = {}) {
 			if (validationOptions.preventSubmit) event.preventDefault();
 			const errors = collectInvalidFields(formElement, validationOptions);
 			applyInlineFeedback(formElement, errors);
+
 			renderErrorSummary(formElement, errors, validationOptions);
 			if (errors.length && validationOptions.focusFirstInvalid) {
 				const target = formElement.querySelector(`#${errors[0].id}`);
@@ -320,6 +361,7 @@ function initO3FormValidation(formOrSelector, options = {}) {
 		if (!current) return;
 		revalidateField(event.target, current.validationOptions);
 	};
+
 	formElement.addEventListener('input', progressiveHandler, true);
 	formElement.addEventListener('blur', progressiveHandler, true);
 	formElement.addEventListener(
diff --git a/components/o3-form/stories/FormValidationHtml.tsx b/components/o3-form/stories/FormValidationHtml.tsx
new file mode 100644
index 0000000000..9cad84d449
--- /dev/null
+++ b/components/o3-form/stories/FormValidationHtml.tsx
@@ -0,0 +1,70 @@
+export const FormValidationHtml = () => {
+	return (
+		<form id="demo-form" className='o3-form'>
+			<div className="o3-form-field" data-testid="first-input">
+				<label
+					className="o3-form-field__label"
+					htmlFor="o3-form-text-input-_9004070302523871"
+				>
+					First name
+				</label>
+				<span
+					className="o3-form-input__description"
+					id="o3-form-description_41273237907367455"
+				>
+          				The name you are referred to by
+        			</span>
+				<input
+					id="o3-form-text-input-_9004070302523871"
+					className="o3-form o3-form-text-input"
+					required
+					aria-required="true"
+					type="text"
+				/>
+			</div>
+			<div className="o3-form-field" data-testid="second-input">
+				<label
+					className="o3-form-field__label"
+					htmlFor="o3-form-text-input-_3017971228893219"
+				>
+					Last name
+				</label>
+				<span
+					className="o3-form-input__description"
+					id="o3-form-description_9230638484727663"
+				>
+          				Your family name
+        			</span>
+				<input
+					id="o3-form-text-input-_3017971228893219"
+					className="o3-form o3-form-text-input"
+					required
+					aria-required="true"
+					type="text"
+				/>
+			</div>
+			<div className="o3-form-field" data-testid="third-input">
+				<label
+					className="o3-form-field__label"
+					htmlFor="o3-form-text-input-_9285747170073946"
+				>
+					CVV code
+				</label>
+				<span
+					className="o3-form-input__description"
+					id="o3-form-description_03257263157199375"
+				>
+          				We're definitely not stealing your data
+        			</span>
+				<input
+					id="o3-form-text-input-_9285747170073946"
+					className="o3-form o3-form-text-input"
+					required
+					aria-required="true"
+					type="text"
+				/>
+			</div>
+			<button className="o3-button o3-button--primary" type="submit">Submit</button>
+		</form>
+	)
+}
diff --git a/components/o3-form/stories/formValidation.stories.tsx b/components/o3-form/stories/formValidation.stories.tsx
index ac8942c80a..73a7b27d87 100644
--- a/components/o3-form/stories/formValidation.stories.tsx
+++ b/components/o3-form/stories/formValidation.stories.tsx
@@ -8,7 +8,8 @@ import '../src/css/brands/professional.css';
 import '../src/css/brands/internal.css';
 import '../src/css/brands/whitelabel.css';
 import '../src/css/brands/sustainable-views.css';
-import { initO3FormValidation} from "../src/js/validation";
+import {initO3FormValidation} from "../src/js/validation";
+import {FormValidationHtml} from "./FormValidationHtml";
 
 const meta: Meta<typeof FormTsx> = {
 	title: 'o3-form',
@@ -44,84 +45,13 @@ export const FormValidation = {
 		},
 	},
 	render: args => {
-		return (
-			// Use HTML instead of TSX to replicate a real-world use case of validation.js
-			<form id="demo-form" className='demo-form'>
-				<div className="o3-form-field">
-					<label
-						className="o3-form-field__label"
-						htmlFor="o3-form-text-input-_9004070302523871"
-					>
-						First name
-					</label>
-					<span
-						className="o3-form-input__description"
-						id="o3-form-description_41273237907367455"
-					>
-          				The name you are referred to by
-        			</span>
-					<input
-						id="o3-form-text-input-_9004070302523871"
-						className="o3-form o3-form-text-input"
-						required
-						aria-required="true"
-						type="text"
-					/>
-				</div>
-				<div className="o3-form-field">
-					<label
-						className="o3-form-field__label"
-						htmlFor="o3-form-text-input-_3017971228893219"
-					>
-						Last name
-					</label>
-					<span
-						className="o3-form-input__description"
-						id="o3-form-description_9230638484727663"
-					>
-          				Your family name
-        			</span>
-					<input
-						id="o3-form-text-input-_3017971228893219"
-						className="o3-form o3-form-text-input"
-						required
-						aria-required="true"
-						type="text"
-					/>
-				</div>
-				<div className="o3-form-field">
-					<label
-						className="o3-form-field__label"
-						htmlFor="o3-form-text-input-_9285747170073946"
-					>
-						CVV code
-					</label>
-					<span
-						className="o3-form-input__description"
-						id="o3-form-description_03257263157199375"
-					>
-          				We're definitely not stealing your data
-        			</span>
-					<input
-						id="o3-form-text-input-_9285747170073946"
-						className="o3-form o3-form-text-input"
-						required
-						aria-required="true"
-						type="text"
-					/>
-				</div>
-				<button className="o3-button o3-button--primary" type="submit">Submit</button>
-			</form>
-		);
+		return <FormValidationHtml/>;
 	},
-	play: async ({ canvasElement }) => {
+	play: async ({canvasElement}) => {
 		const form = canvasElement.querySelector(
 			'#demo-form'
 		) as HTMLFormElement | null;
 
-		console.log('[play] form from canvasElement:', form);
-
-		form.addEventListener('submit', e => console.log('[basic] submit fired', e));
 		if (form) {
 			initO3FormValidation(form);
 		}
diff --git a/components/o3-form/stories/formValidation.test.stories.tsx b/components/o3-form/stories/formValidation.test.stories.tsx
new file mode 100644
index 0000000000..8a2329dcfe
--- /dev/null
+++ b/components/o3-form/stories/formValidation.test.stories.tsx
@@ -0,0 +1,97 @@
+import type {Meta} from '@storybook/react';
+import {expect, userEvent, within} from '@storybook/test';
+import links from '@financial-times/o3-figma-sb-links';
+
+import {Form as FormTsx} from '../src/tsx';
+
+import '../src/css/brands/core.css';
+import '../src/css/brands/professional.css';
+import '../src/css/brands/internal.css';
+import '../src/css/brands/whitelabel.css';
+import '../src/css/brands/sustainable-views.css';
+import {initO3FormValidation} from "../src/js/validation";
+import {FormValidationHtml} from "./FormValidationHtml";
+
+const meta: Meta<typeof FormTsx> = {
+	title: 'Tests/o3-form',
+	component: FormTsx,
+	tags: [
+		'experimental',
+		'core',
+		'professional',
+		'internal',
+		'whitelabel',
+		'sustainable-views',
+	],
+	decorators: [
+		Story => (
+			<div data-o3-brand="core" className="o3-grid">
+				<div
+					style={{gridColumn: `content-start / content-end`}}>
+					<Story/>
+				</div>
+			</div>
+		),
+	],
+	parameters: {
+		backgrounds: {disable: true},
+	},
+} as Meta;
+
+export const FormValidation = {
+	parameters: {
+		design: {
+			type: 'figma',
+			url: links['whitelabel-o3-form--text-input'].figma,
+		},
+	},
+	render: args => {
+		return <FormValidationHtml/>;
+	},
+	play: async ({canvasElement}) => {
+		const canvas = within(canvasElement);
+		const form = canvasElement.querySelector(
+			'#demo-form'
+		) as HTMLFormElement | null;
+
+		if (form) {
+			initO3FormValidation(form);
+		}
+
+		const firstInput = within(canvas.getByTestId('first-input'));
+		const firstInputElement = firstInput.getByRole('textbox');
+
+		const secondInput = within(canvas.getByTestId('second-input'));
+		const secondInputElement = secondInput.getByRole('textbox');
+
+		const thirdInput = within(canvas.getByTestId('third-input'));
+		const thirdInputElement = thirdInput.getByRole('textbox');
+
+		// Whenn clicking through the form.
+		await userEvent.click(firstInputElement);
+		await userEvent.click(secondInputElement);
+		await userEvent.click(thirdInputElement);
+
+		// It should highlight the first input field as invalid
+		expect(firstInput.queryByText('Please fill in this field.')).toBeInTheDocument();
+		expect(firstInputElement.classList).toContain('o3-form-text-input--error');
+
+		// It should highlight the second input field as invalid
+		expect(secondInput.queryByText('Please fill in this field.')).toBeInTheDocument();
+		expect(secondInputElement.classList).toContain('o3-form-text-input--error');
+
+		// It should not highlight the third input field as invalid
+		expect(thirdInput.queryByText('Please fill in this field.')).not.toBeInTheDocument();
+		expect(thirdInputElement.classList).not.toContain('o3-form-text-input--error');
+
+		// When correcting an error
+		await userEvent.click(firstInputElement);
+		await userEvent.type(firstInputElement, 'My resolving text');
+
+		// It should not highlight the first input field as invalid
+		expect(firstInput.queryByText('Please fill in this field.')).not.toBeInTheDocument();
+		expect(firstInputElement.classList).not.toContain('o3-form-text-input--error');
+	},
+};
+
+export default meta;

From 493379f2ac55752c9f64203847009b7fc1ac356a Mon Sep 17 00:00:00 2001
From: "ben.freshwater" <ben.freshwater@ft.com>
Date: Wed, 7 Jan 2026 09:32:52 +0000
Subject: [PATCH 04/22] chore: refactor validation.js

---
 components/o3-form/src/js/validation.js | 47 ++++++++++++++++++++-----
 1 file changed, 39 insertions(+), 8 deletions(-)

diff --git a/components/o3-form/src/js/validation.js b/components/o3-form/src/js/validation.js
index 98cedf6185..6151261d11 100644
--- a/components/o3-form/src/js/validation.js
+++ b/components/o3-form/src/js/validation.js
@@ -37,13 +37,21 @@ const formState = new WeakMap();
  */
 function deriveFieldName(element) {
 	if (!element) return 'Field';
+
 	if (element.id) {
 		const label = element.form?.querySelector(`label[for="${element.id}"]`);
 		if (label && label.textContent) return label.textContent.trim();
 	}
+
 	return element.getAttribute('name') || element.id || 'Field';
 }
 
+/**
+ * Check if a given HTMLElement is a valid form field element.
+ *
+ * @param fieldElement {HTMLElement}
+ * @returns {boolean}
+ */
 function isFormFieldElement(fieldElement) {
 	return fieldElement instanceof HTMLInputElement ||
 		fieldElement instanceof HTMLSelectElement ||
@@ -61,8 +69,8 @@ function collectInvalidFields(formElement, validationOptions) {
 	const elements = Array.from(formElement.elements);
 	/** @type {FieldError[]} */
 	const errors = [];
-	for (const fieldElement of elements) {
 
+	for (const fieldElement of elements) {
 		if (!isFormFieldElement(fieldElement))
 			continue;
 
@@ -84,6 +92,7 @@ function collectInvalidFields(formElement, validationOptions) {
 		} else {
 			// Data attribute overrides (e.g. data-o3-form-message-required)
 			const validity = fieldElement.validity;
+
 			const dataKey = validity.valueMissing
 				? 'required'
 				: validity.typeMismatch
@@ -103,10 +112,12 @@ function collectInvalidFields(formElement, validationOptions) {
 											: validity.badInput
 												? 'bad-input'
 												: null;
+
 			if (dataKey) {
 				const attr = fieldElement.getAttribute(
 					`data-o3-form-message-${dataKey}`
 				);
+
 				if (attr) {
 					message = attr;
 					source = 'custom';
@@ -133,6 +144,7 @@ function collectInvalidFields(formElement, validationOptions) {
 function applyInlineFeedback(formElement, errors) {
 	const invalidIds = new Set(errors.map(error => error.id));
 	const elements = Array.from(formElement.elements);
+
 	for (const fieldElement of elements) {
 		if (!(fieldElement instanceof HTMLElement)) continue;
 
@@ -160,11 +172,14 @@ function applyInlineFeedback(formElement, errors) {
  */
 function renderErrorSummary(formElement, errors, validationOptions) {
 	if (!validationOptions.errorSummary) return;
+
 	let summary = formElement.querySelector(SUMMARY_SELECTOR);
+
 	if (!errors.length) {
 		if (summary) summary.remove();
 		return;
 	}
+
 	if (!summary) {
 		summary = document.createElement('div');
 		summary.className = SUMMARY_CLASS;
@@ -173,27 +188,35 @@ function renderErrorSummary(formElement, errors, validationOptions) {
 		formElement.insertBefore(summary, formElement.firstChild);
 	}
 	summary.innerHTML = '';
+
 	const icon = document.createElement('span');
 	icon.className = 'o3-form__error-summary-icon';
+
 	const headingWrapper = document.createElement('div');
 	headingWrapper.className = 'o3-form__error-summary__heading';
 	headingWrapper.setAttribute('aria-labelledby', 'error-summary-title');
+
 	const heading = document.createElement('span');
 	heading.id = 'error-summary-title';
 	heading.className = 'o3-typography-heading5';
 	heading.textContent = 'Please correct these errors and try again.';
+
 	const list = document.createElement('ul');
 	list.className = 'o3-forms__error-summary__list o3-typography-body-small';
+
 	for (const error of errors) {
 		const listItem = document.createElement('li');
+
 		if (error.id) {
 			const link = document.createElement('a');
 			link.className = 'o3-typography-link';
 			link.href = `#${error.id}`;
 			link.textContent = error.fieldName;
 			listItem.appendChild(link);
+
 			const messageSpan = document.createElement('span');
 			messageSpan.textContent = `: ${error.message}`;
+
 			listItem.appendChild(messageSpan);
 		} else {
 			listItem.textContent = `${error.fieldName}: ${error.message}`;
@@ -202,8 +225,10 @@ function renderErrorSummary(formElement, errors, validationOptions) {
 	}
 	headingWrapper.appendChild(heading);
 	headingWrapper.appendChild(list);
+
 	summary.appendChild(icon);
 	summary.appendChild(headingWrapper);
+
 	if (validationOptions.focusFirstInvalid) {
 		heading.focus?.();
 	}
@@ -218,10 +243,12 @@ function renderErrorSummary(formElement, errors, validationOptions) {
 function createFeedbackElement(error) {
 	const errorMessageContainer = document.createElement('div');
 	errorMessageContainer.classList.add('o3-form-feedback', 'o3-form-feedback__error');
+
 	const errorMessage = document.createElement('span');
 	errorMessage.classList.add('o3-form-feedback__error-message');
 	errorMessage.innerText = error.message;
 	errorMessageContainer.appendChild(errorMessage);
+
 	return errorMessageContainer;
 }
 
@@ -233,23 +260,19 @@ function createFeedbackElement(error) {
  * @returns {FieldError|null} A field error if invalid, otherwise null.
  */
 function revalidateField(element, validationOptions) {
-	if (
-		!(
-			element instanceof HTMLInputElement ||
-			element instanceof HTMLSelectElement ||
-			element instanceof HTMLTextAreaElement
-		)
-	) {
+	if (!isFormFieldElement(element)) {
 		return null;
 	}
 
 	if (element.checkValidity()) {
 		// clear custom validity if previously set
 		element.setCustomValidity('');
+
 		if (element.classList.contains('o3-form-text-input')) {
 			element.classList.remove(ERROR_INPUT_CLASS);
 			element.parentElement.querySelector('.o3-form-feedback__error')?.remove();
 		}
+
 		if (
 			element.classList.contains('o3-form-input-radio-button') ||
 			element.classList.contains('o3-form-input-checkbox__input')
@@ -257,6 +280,7 @@ function revalidateField(element, validationOptions) {
 			element.classList.remove(ERROR_CHECK_CLASS);
 			element.parentElement.querySelector('.o3-form-feedback__error')?.remove();
 		}
+
 		return null;
 	}
 
@@ -326,9 +350,11 @@ function initO3FormValidation(formOrSelector, options = {}) {
 		},
 		options
 	);
+
 	if (validationOptions.useBrowserReport && validationOptions.preventSubmit) {
 		throw new Error('Cannot enable both useBrowserReport and preventSubmit.');
 	}
+
 	if (formState.has(formElement)) return formElement; // already initialised
 
 	const state = {validationOptions}; // future: may hold cached lastErrors etc.
@@ -390,12 +416,17 @@ function destroyO3FormValidation(formOrSelector) {
 		formOrSelector instanceof HTMLFormElement
 			? formOrSelector
 			: document.querySelector(formOrSelector);
+
 	if (!formElement || !(formElement instanceof HTMLFormElement)) return;
+
 	const state = formState.get(formElement);
+
 	if (!state) return;
+
 	// clone without listeners (simpler than tracking each bound handler)
 	const clone = formElement.cloneNode(true);
 	formElement.parentNode?.replaceChild(clone, formElement);
+
 	const summary = clone.querySelector(SUMMARY_SELECTOR);
 	summary?.remove();
 	formState.delete(clone); // new clone not initialised

From 75f4ea5d026ed51866b3f2008287b56bb6736f54 Mon Sep 17 00:00:00 2001
From: "ben.freshwater" <ben.freshwater@ft.com>
Date: Thu, 8 Jan 2026 11:51:45 +0000
Subject: [PATCH 05/22] fix: fix error display and refactor

---
 components/o3-form/src/js/validation.js       | 210 +++++++++---------
 .../o3-form/stories/FormValidationHtml.tsx    |   2 +-
 .../stories/formValidation.stories.tsx        |   4 +
 .../stories/formValidation.test.stories.tsx   |  96 +++++++-
 4 files changed, 204 insertions(+), 108 deletions(-)

diff --git a/components/o3-form/src/js/validation.js b/components/o3-form/src/js/validation.js
index 6151261d11..28f2946614 100644
--- a/components/o3-form/src/js/validation.js
+++ b/components/o3-form/src/js/validation.js
@@ -28,6 +28,8 @@ const ERROR_CHECK_CLASS = 'o3-form-input-error';
 
 /** Maintain internal state per form element */
 const formState = new WeakMap();
+const elementsPreviouslyFocussed = [];
+let isSubmitAttempted = false;
 
 /**
  * Derive a human readable field name from its associated `<label>` or fallback attributes.
@@ -142,23 +144,24 @@ function collectInvalidFields(formElement, validationOptions) {
  * @param {FieldError[]} errors Current list of errors to reflect.
  */
 function applyInlineFeedback(formElement, errors) {
-	const invalidIds = new Set(errors.map(error => error.id));
-	const elements = Array.from(formElement.elements);
+	const elements = Array.from(formElement.elements)
 
 	for (const fieldElement of elements) {
 		if (!(fieldElement instanceof HTMLElement)) continue;
 
-		const isInvalid = fieldElement.id && invalidIds.has(fieldElement.id);
-
-		if (fieldElement.classList.contains('o3-form-text-input') && !fieldElement.classList.contains(ERROR_INPUT_CLASS)) {
-			fieldElement.classList.toggle(ERROR_INPUT_CLASS, isInvalid);
-		}
+		const [error] = errors.filter((error) => error.id === fieldElement.id);
+		if (!error) {
+			fieldElement.closest('.o3-form-field')?.querySelector('.o3-form-feedback__error')?.remove();
+			fieldElement.classList.remove(ERROR_INPUT_CLASS);
+		} else {
+			if (fieldElement.classList.contains('o3-form-text-input') && !fieldElement.classList.contains(ERROR_INPUT_CLASS)) {
+				fieldElement.classList.add(ERROR_INPUT_CLASS);
+			}
 
-		if (
-			(fieldElement.classList.contains('o3-form-input-radio-button') ||
-				fieldElement.classList.contains('o3-form-input-checkbox__input')) && !fieldElement.clasList.contains(ERROR_CHECK_CLASS)
-		) {
-			fieldElement.classList.toggle(ERROR_CHECK_CLASS, isInvalid);
+			if (!fieldElement.parentElement.querySelector('.o3-form-feedback__error')) {
+				const errorMessageContainer = createFeedbackElement(error);
+				fieldElement.closest('.o3-form-field').appendChild(errorMessageContainer);
+			}
 		}
 	}
 }
@@ -170,7 +173,7 @@ function applyInlineFeedback(formElement, errors) {
  * @param {FieldError[]} errors Errors to list; if empty the summary is removed.
  * @param {O3ValidationOptions} validationOptions Validation configuration.
  */
-function renderErrorSummary(formElement, errors, validationOptions) {
+function createErrorSummary(formElement, errors, validationOptions) {
 	if (!validationOptions.errorSummary) return;
 
 	let summary = formElement.querySelector(SUMMARY_SELECTOR);
@@ -252,65 +255,6 @@ function createFeedbackElement(error) {
 	return errorMessageContainer;
 }
 
-/**
- * Revalidate a single field and update inline feedback (does not rebuild summary).
- *
- * @param {HTMLElement} element The field to revalidate.
- * @param {O3ValidationOptions} validationOptions Validation configuration.
- * @returns {FieldError|null} A field error if invalid, otherwise null.
- */
-function revalidateField(element, validationOptions) {
-	if (!isFormFieldElement(element)) {
-		return null;
-	}
-
-	if (element.checkValidity()) {
-		// clear custom validity if previously set
-		element.setCustomValidity('');
-
-		if (element.classList.contains('o3-form-text-input')) {
-			element.classList.remove(ERROR_INPUT_CLASS);
-			element.parentElement.querySelector('.o3-form-feedback__error')?.remove();
-		}
-
-		if (
-			element.classList.contains('o3-form-input-radio-button') ||
-			element.classList.contains('o3-form-input-checkbox__input')
-		) {
-			element.classList.remove(ERROR_CHECK_CLASS);
-			element.parentElement.querySelector('.o3-form-feedback__error')?.remove();
-		}
-
-		return null;
-	}
-
-	const errors = collectInvalidFields(element.form, validationOptions).filter(
-		e => e.id === element.id
-	);
-
-	applyInlineFeedback(element.form, errors);
-
-	const [error] = errors;
-	if (error) {
-		if (!element.parentElement.querySelector('.o3-form-feedback__error')) {
-			const errorMessageContainer = createFeedbackElement(error);
-			element.closest('.o3-form-field').appendChild(errorMessageContainer);
-		}
-
-		if (element.classList.contains('o3-form-text-input'))
-			element.classList.add(ERROR_INPUT_CLASS);
-
-
-		if (
-			element.classList.contains('o3-form-input-radio-button') ||
-			element.classList.contains('o3-form-input-checkbox__input')
-		)
-			element.classList.add(ERROR_CHECK_CLASS);
-		return error;
-	}
-	return null;
-}
-
 /**
  * Set a custom message for a field; clears any previous message when falsy.
  *
@@ -322,6 +266,30 @@ function setCustomMessage(element, message) {
 	element.setCustomValidity(message || '');
 }
 
+/**
+ * Validates form is valid and conditionally displays an error summary
+ * @param formElement
+ * @param validationOptions
+ * @returns boolean
+ */
+function validateAndReRender(formElement, validationOptions) {
+	const invalid = !formElement.checkValidity();
+	if (invalid) {
+		const errors = collectInvalidFields(formElement, validationOptions);
+		applyInlineFeedback(formElement, errors);
+		createErrorSummary(formElement, errors, validationOptions);
+
+		if (errors.length && validationOptions.focusFirstInvalid) {
+			const target = formElement.querySelector(`#${errors[0].id}`);
+			target?.focus();
+		}
+	} else {
+		document.querySelector(SUMMARY_SELECTOR)?.remove();
+	}
+
+	return !invalid;
+}
+
 /**
  * Initialise validation on a form element or selector.
  *
@@ -360,49 +328,80 @@ function initO3FormValidation(formOrSelector, options = {}) {
 	const state = {validationOptions}; // future: may hold cached lastErrors etc.
 	formState.set(formElement, state);
 
-	formElement.addEventListener('submit', event => {
-		const current = formState.get(formElement);
-		if (!current) return;
-		const {validationOptions} = current;
-		const invalid = !formElement.checkValidity();
-		if (invalid) {
-			if (validationOptions.preventSubmit) event.preventDefault();
-			const errors = collectInvalidFields(formElement, validationOptions);
-			applyInlineFeedback(formElement, errors);
-
-			renderErrorSummary(formElement, errors, validationOptions);
-			if (errors.length && validationOptions.focusFirstInvalid) {
-				const target = formElement.querySelector(`#${errors[0].id}`);
-				target?.focus();
-			}
-			if (validationOptions.useBrowserReport) {
-				formElement.reportValidity();
-			}
-		}
-	});
-
-	// progressive revalidation
-	const progressiveHandler = event => {
-		const current = formState.get(formElement);
-		if (!current) return;
-		revalidateField(event.target, current.validationOptions);
-	};
-
-	formElement.addEventListener('input', progressiveHandler, true);
-	formElement.addEventListener('blur', progressiveHandler, true);
 	formElement.addEventListener(
 		'invalid',
 		event => {
 			// suppress native tooltip when using custom summary
 			const current = formState.get(formElement);
 			if (!current) return;
-			if (current.validationOptions.errorSummary) {
-				event.preventDefault();
+			if (isSubmitAttempted) {
+				const errors = collectInvalidFields(formElement, validationOptions);
+				applyInlineFeedback(formElement, errors);
+				createErrorSummary(formElement, errors, validationOptions);
+				if (current.validationOptions.errorSummary) {
+					event.preventDefault();
+				}
+				isSubmitAttempted = false;
+				console.log('submitted false on invalid event');
 			}
 		},
 		true
 	);
 
+	// progressive revalidation
+	const progressiveHandler = event => {
+		const current = formState.get(formElement);
+		if (!current) return;
+		const errors = collectInvalidFields(event.currentTarget, validationOptions);
+
+		const focussedErrors = isSubmitAttempted ? errors : errors.filter((error) => elementsPreviouslyFocussed.includes(error.id));
+
+		applyInlineFeedback(formElement, focussedErrors);
+	};
+
+	formElement.addEventListener('submit', (event) => {
+		isSubmitAttempted = true;
+
+		const ok = validateAndReRender(formElement, validationOptions);
+		if (!ok && validationOptions.preventSubmit) event.preventDefault();
+	});
+
+	formElement.addEventListener('pointerdown', event => {
+		const target = event.target.closest('button[type="submit"], input[type="submit"]');
+
+		const isSubmit =
+			target instanceof HTMLButtonElement
+				? target.type === 'submit'
+				: target instanceof HTMLInputElement && target.type === 'submit';
+
+		if (!isSubmit) return;
+		isSubmitAttempted = true;
+
+		const current = formState.get(formElement);
+		if (!current) return;
+		const {validationOptions} = current;
+
+		for (const fieldElement of formElement.elements) {
+			elementsPreviouslyFocussed.push(fieldElement.id);
+		}
+
+		const ok = validateAndReRender(formElement, validationOptions);
+		if (!ok && validationOptions.preventSubmit) event.preventDefault();
+	}, true);
+
+	formElement.addEventListener('input', progressiveHandler, true);
+	formElement.addEventListener('blur', progressiveHandler, true);
+
+	const fieldElements = Array.from(formElement.elements);
+
+	for (const fieldElement of fieldElements) {
+		if (!isFormFieldElement(fieldElement)) continue;
+
+		fieldElement.addEventListener('focusin', () => {
+			elementsPreviouslyFocussed.push(fieldElement.id);
+		});
+	}
+
 	return formElement;
 }
 
@@ -436,7 +435,6 @@ export {
 	collectInvalidFields,
 	destroyO3FormValidation,
 	initO3FormValidation,
-	revalidateField,
 	setCustomMessage,
-	renderErrorSummary as showErrorSummary,
+	createErrorSummary as showErrorSummary,
 };
diff --git a/components/o3-form/stories/FormValidationHtml.tsx b/components/o3-form/stories/FormValidationHtml.tsx
index 9cad84d449..5b3bcdea51 100644
--- a/components/o3-form/stories/FormValidationHtml.tsx
+++ b/components/o3-form/stories/FormValidationHtml.tsx
@@ -64,7 +64,7 @@ export const FormValidationHtml = () => {
 					type="text"
 				/>
 			</div>
-			<button className="o3-button o3-button--primary" type="submit">Submit</button>
+			<input data-testid="submit-button" className="o3-button o3-button--primary" type="submit" value="Submit"/>
 		</form>
 	)
 }
diff --git a/components/o3-form/stories/formValidation.stories.tsx b/components/o3-form/stories/formValidation.stories.tsx
index 73a7b27d87..c8b53ec832 100644
--- a/components/o3-form/stories/formValidation.stories.tsx
+++ b/components/o3-form/stories/formValidation.stories.tsx
@@ -55,6 +55,10 @@ export const FormValidation = {
 		if (form) {
 			initO3FormValidation(form);
 		}
+
+		form?.addEventListener('submit', (event) => {
+			event.preventDefault();
+		});
 	},
 };
 
diff --git a/components/o3-form/stories/formValidation.test.stories.tsx b/components/o3-form/stories/formValidation.test.stories.tsx
index 8a2329dcfe..e241bc7731 100644
--- a/components/o3-form/stories/formValidation.test.stories.tsx
+++ b/components/o3-form/stories/formValidation.test.stories.tsx
@@ -38,7 +38,7 @@ const meta: Meta<typeof FormTsx> = {
 	},
 } as Meta;
 
-export const FormValidation = {
+export const FormValidationDisplaysElementErrorSummary = {
 	parameters: {
 		design: {
 			type: 'figma',
@@ -94,4 +94,98 @@ export const FormValidation = {
 	},
 };
 
+export const FormValidtionDisplaysErrorSummary = {
+	parameters: {
+		design: {
+			type: 'figma',
+			url: links['whitelabel-o3-form--text-input'].figma,
+		},
+	},
+	render: args => {
+		return <FormValidationHtml/>;
+	},
+	play: async ({canvasElement}) => {
+		const canvas = within(canvasElement);
+		const form = canvasElement.querySelector(
+			'#demo-form'
+		) as HTMLFormElement | null;
+
+		if (form) {
+			initO3FormValidation(form);
+		} else {
+			return false;
+		}
+
+		// When submitting an empty form
+		const submitButton = canvas.getByTestId('submit-button');
+		await userEvent.click(submitButton);
+
+		// It should render an error summary
+		expect(canvasElement.querySelector('.o3-form__error-summary')).toBeInTheDocument();
+
+		// It should list all erroring fields with a reason
+		expect(canvas.queryByText(getErrorSummaryLineItemText('First name'))).toBeInTheDocument();
+		expect(canvas.queryByText(getErrorSummaryLineItemText('Last name'))).toBeInTheDocument();
+		expect(canvas.queryByText(getErrorSummaryLineItemText('CVV code'))).toBeInTheDocument();
+
+		const firstInput = within(canvas.getByTestId('first-input'));
+		const firstInputElement = firstInput.getByRole('textbox');
+
+		const secondInput = within(canvas.getByTestId('second-input'));
+		const secondInputElement = secondInput.getByRole('textbox');
+
+		const thirdInput = within(canvas.getByTestId('third-input'));
+		const thirdInputElement = thirdInput.getByRole('textbox');
+
+		// It should highlight the first input field as invalid
+		expect(firstInput.queryByText('Please fill in this field.')).toBeInTheDocument();
+		expect(firstInputElement.classList).toContain('o3-form-text-input--error');
+
+		// It should highlight the second input field as invalid
+		expect(secondInput.queryByText('Please fill in this field.')).toBeInTheDocument();
+		expect(secondInputElement.classList).toContain('o3-form-text-input--error');
+
+		// It should not highlight the third input field as invalid
+		expect(thirdInput.queryByText('Please fill in this field.')).toBeInTheDocument();
+		expect(thirdInputElement.classList).toContain('o3-form-text-input--error');
+
+		// When resolving one field
+		await userEvent.type(firstInputElement, 'My resolving text');
+		await userEvent.click(submitButton);
+
+		// It should list only erroring fields with a reason
+		expect(canvas.queryByText(getErrorSummaryLineItemText('First name'))).not.toBeInTheDocument();
+		expect(canvas.queryByText(getErrorSummaryLineItemText('Last name'))).toBeInTheDocument();
+		expect(canvas.queryByText(getErrorSummaryLineItemText('CVV code'))).toBeInTheDocument();
+
+		// It should not highlight the first input field as invalid
+		expect(firstInput.queryByText('Please fill in this field.')).not.toBeInTheDocument();
+		expect(firstInputElement.classList).not.toContain('o3-form-text-input--error');
+
+		// It should highlight the second input field as invalid
+		expect(secondInput.queryByText('Please fill in this field.')).toBeInTheDocument();
+		expect(secondInputElement.classList).toContain('o3-form-text-input--error');
+
+		// It should not highlight the third input field as invalid
+		expect(thirdInput.queryByText('Please fill in this field.')).toBeInTheDocument();
+		expect(thirdInputElement.classList).toContain('o3-form-text-input--error');
+
+		// When resolving all other fields.
+		form.addEventListener('submit', (event) => {
+			event.preventDefault();
+		});
+		await userEvent.type(secondInputElement, 'My resolving text');
+		await userEvent.type(thirdInputElement, 'My resolving text');
+		await userEvent.click(submitButton);
+
+		// It should not display the error summary
+		expect(canvasElement.querySelector('.o3-form__error-summary')).not.toBeInTheDocument();
+	},
+};
+
+const getErrorSummaryLineItemText = (expectedText: string) => (text: string, element: HTMLElement) => {
+	return element.textContent === `${expectedText}: Please fill in this field.`;
+
+}
+
 export default meta;

From ddee9b5ddca2fdafb3808d6d03dd522dc5bbae47 Mon Sep 17 00:00:00 2001
From: "ben.freshwater" <ben.freshwater@ft.com>
Date: Thu, 8 Jan 2026 12:37:01 +0000
Subject: [PATCH 06/22] chore: reorder functions in order of usage depth

---
 components/o3-form/src/js/validation.js | 353 ++++++++++++------------
 1 file changed, 179 insertions(+), 174 deletions(-)

diff --git a/components/o3-form/src/js/validation.js b/components/o3-form/src/js/validation.js
index 28f2946614..c7997a6597 100644
--- a/components/o3-form/src/js/validation.js
+++ b/components/o3-form/src/js/validation.js
@@ -32,32 +32,118 @@ const elementsPreviouslyFocussed = [];
 let isSubmitAttempted = false;
 
 /**
- * Derive a human readable field name from its associated `<label>` or fallback attributes.
+ * Initialise validation on a form element or selector.
  *
- * @param {HTMLInputElement|HTMLSelectElement|HTMLTextAreaElement} element The form control to derive a label for.
- * @returns {string} A human friendly name for the field.
+ * @param {string|HTMLFormElement} formOrSelector A form element or a selector resolving to one.
+ * @param {O3ValidationOptions} [options] Validation configuration overrides.
+ * @returns {HTMLFormElement|null} The initialised form element.
  */
-function deriveFieldName(element) {
-	if (!element) return 'Field';
+function initO3FormValidation(formOrSelector, options = {}) {
+	const formElement =
+		formOrSelector instanceof HTMLFormElement
+			? formOrSelector
+			: document.querySelector(formOrSelector);
 
-	if (element.id) {
-		const label = element.form?.querySelector(`label[for="${element.id}"]`);
-		if (label && label.textContent) return label.textContent.trim();
+	if (!formElement || !(formElement instanceof HTMLFormElement)) {
+		throw new Error(
+			'initO3FormValidation must be passed a form element or selector resolving to a form.'
+		);
 	}
+	const validationOptions = Object.assign(
+		{
+			useBrowserReport: false,
+			errorSummary: true,
+			customMessages: undefined,
+			preventSubmit: true,
+			focusFirstInvalid: true,
+		},
+		options
+	);
 
-	return element.getAttribute('name') || element.id || 'Field';
-}
+	if (validationOptions.useBrowserReport && validationOptions.preventSubmit) {
+		throw new Error('Cannot enable both useBrowserReport and preventSubmit.');
+	}
 
-/**
- * Check if a given HTMLElement is a valid form field element.
- *
- * @param fieldElement {HTMLElement}
- * @returns {boolean}
- */
-function isFormFieldElement(fieldElement) {
-	return fieldElement instanceof HTMLInputElement ||
-		fieldElement instanceof HTMLSelectElement ||
-		fieldElement instanceof HTMLTextAreaElement;
+	if (formState.has(formElement)) return formElement; // already initialised
+
+	const state = {validationOptions}; // future: may hold cached lastErrors etc.
+	formState.set(formElement, state);
+
+	const progressiveHandler = event => {
+		const current = formState.get(formElement);
+		if (!current) return;
+		const errors = collectInvalidFields(event.currentTarget, validationOptions);
+
+		const focussedErrors = isSubmitAttempted ? errors : errors.filter((error) => elementsPreviouslyFocussed.includes(error.id));
+
+		applyInlineFeedback(formElement, focussedErrors);
+	};
+
+	formElement.addEventListener(
+		'invalid',
+		event => {
+			// suppress native tooltip when using custom summary
+			const current = formState.get(formElement);
+			if (!current) return;
+			if (isSubmitAttempted) {
+				const errors = collectInvalidFields(formElement, validationOptions);
+				applyInlineFeedback(formElement, errors);
+				createErrorSummary(formElement, errors, validationOptions);
+				if (current.validationOptions.errorSummary) {
+					event.preventDefault();
+				}
+				isSubmitAttempted = false;
+			}
+		},
+		true
+	);
+
+	formElement.addEventListener('submit', (event) => {
+		isSubmitAttempted = true;
+
+		const ok = validateAndReRender(formElement, validationOptions);
+
+		if (!ok && validationOptions.preventSubmit) event.preventDefault();
+	});
+
+	formElement.addEventListener('pointerdown', event => {
+		const target = event.target.closest('button[type="submit"], input[type="submit"]');
+
+		const isSubmit =
+			target instanceof HTMLButtonElement
+				? target.type === 'submit'
+				: target instanceof HTMLInputElement && target.type === 'submit';
+
+		if (!isSubmit) return;
+		isSubmitAttempted = true;
+
+		const current = formState.get(formElement);
+		if (!current) return;
+		const {validationOptions} = current;
+
+		for (const fieldElement of formElement.elements) {
+			elementsPreviouslyFocussed.push(fieldElement.id);
+		}
+
+		const ok = validateAndReRender(formElement, validationOptions);
+
+		if (!ok && validationOptions.preventSubmit) event.preventDefault();
+	}, true);
+
+	formElement.addEventListener('input', progressiveHandler, true);
+	formElement.addEventListener('blur', progressiveHandler, true);
+
+	const fieldElements = Array.from(formElement.elements);
+
+	for (const fieldElement of fieldElements) {
+		if (!isFormFieldElement(fieldElement)) continue;
+
+		fieldElement.addEventListener('focusin', () => {
+			elementsPreviouslyFocussed.push(fieldElement.id);
+		});
+	}
+
+	return formElement;
 }
 
 /**
@@ -68,6 +154,7 @@ function isFormFieldElement(fieldElement) {
  * @returns {FieldError[]} An array of field error objects.
  */
 function collectInvalidFields(formElement, validationOptions) {
+	/** @type {HTMLElement[]} */
 	const elements = Array.from(formElement.elements);
 	/** @type {FieldError[]} */
 	const errors = [];
@@ -78,6 +165,7 @@ function collectInvalidFields(formElement, validationOptions) {
 
 		if (fieldElement.checkValidity()) continue;
 
+		/** @type string */
 		let message = fieldElement.validationMessage;
 		let source = 'native';
 
@@ -150,6 +238,7 @@ function applyInlineFeedback(formElement, errors) {
 		if (!(fieldElement instanceof HTMLElement)) continue;
 
 		const [error] = errors.filter((error) => error.id === fieldElement.id);
+
 		if (!error) {
 			fieldElement.closest('.o3-form-field')?.querySelector('.o3-form-feedback__error')?.remove();
 			fieldElement.classList.remove(ERROR_INPUT_CLASS);
@@ -158,14 +247,58 @@ function applyInlineFeedback(formElement, errors) {
 				fieldElement.classList.add(ERROR_INPUT_CLASS);
 			}
 
-			if (!fieldElement.parentElement.querySelector('.o3-form-feedback__error')) {
+			if (!fieldElement.parentElement.querySelector('.o3-form-feedback__error')) {//TODO: check if need to extract to const
 				const errorMessageContainer = createFeedbackElement(error);
-				fieldElement.closest('.o3-form-field').appendChild(errorMessageContainer);
+				fieldElement.closest('.o3-form-field').appendChild(errorMessageContainer);//TODO: check if need to extract class to const
 			}
 		}
 	}
 }
 
+/**
+ * Validates form is valid and conditionally displays an error summary
+ * @param formElement
+ * @param validationOptions
+ * @returns boolean
+ */
+function validateAndReRender(formElement, validationOptions) {
+	const invalid = !formElement.checkValidity();
+
+	if (invalid) {
+		const errors = collectInvalidFields(formElement, validationOptions);
+
+		applyInlineFeedback(formElement, errors);
+		createErrorSummary(formElement, errors, validationOptions);
+
+		if (errors.length && validationOptions.focusFirstInvalid) {
+			const target = formElement.querySelector(`#${errors[0].id}`);
+			target?.focus();
+		}
+	} else {
+		document.querySelector(SUMMARY_SELECTOR)?.remove();
+	}
+
+	return !invalid;
+}
+
+/**
+ * Creates feedback element
+ *
+ * @param {Error} error The error to create a feedback element for.
+ * @returns {HTMLElement} A field error if invalid, otherwise null.
+ */
+function createFeedbackElement(error) {
+	const errorMessageContainer = document.createElement('div');
+	errorMessageContainer.classList.add('o3-form-feedback', 'o3-form-feedback__error');//TODO: check if need to extract classes to const
+
+	const errorMessage = document.createElement('span');
+	errorMessage.classList.add('o3-form-feedback__error-message');//TODO: check if need to extract classes to const
+	errorMessage.innerText = error.message;
+	errorMessageContainer.appendChild(errorMessage);
+
+	return errorMessageContainer;
+}
+
 /**
  * Render or update the error summary element for the form.
  *
@@ -193,10 +326,10 @@ function createErrorSummary(formElement, errors, validationOptions) {
 	summary.innerHTML = '';
 
 	const icon = document.createElement('span');
-	icon.className = 'o3-form__error-summary-icon';
+	icon.className = 'o3-form__error-summary-icon';//TODO: check if we need to extract to const
 
 	const headingWrapper = document.createElement('div');
-	headingWrapper.className = 'o3-form__error-summary__heading';
+	headingWrapper.className = 'o3-form__error-summary__heading'; //TODO: check if we need to extract to const
 	headingWrapper.setAttribute('aria-labelledby', 'error-summary-title');
 
 	const heading = document.createElement('span');
@@ -238,21 +371,32 @@ function createErrorSummary(formElement, errors, validationOptions) {
 }
 
 /**
- * Creates feedback element
+ * Derive a human-readable field name from its associated `<label>` or fallback attributes.
  *
- * @param {Error} error The error to create a feedback element for.
- * @returns {HTMLElement} A field error if invalid, otherwise null.
+ * @param {HTMLInputElement|HTMLSelectElement|HTMLTextAreaElement} element The form control to derive a label for.
+ * @returns {string} A human friendly name for the field.
  */
-function createFeedbackElement(error) {
-	const errorMessageContainer = document.createElement('div');
-	errorMessageContainer.classList.add('o3-form-feedback', 'o3-form-feedback__error');
+function deriveFieldName(element) {
+	if (!element) return 'Field';
 
-	const errorMessage = document.createElement('span');
-	errorMessage.classList.add('o3-form-feedback__error-message');
-	errorMessage.innerText = error.message;
-	errorMessageContainer.appendChild(errorMessage);
+	if (element.id) {
+		const label = element.form?.querySelector(`label[for="${element.id}"]`);
+		if (label && label.textContent) return label.textContent.trim();
+	}
 
-	return errorMessageContainer;
+	return element.getAttribute('name') || element.id || 'Field';
+}
+
+/**
+ * Check if a given HTMLElement is a valid form field element.
+ *
+ * @param fieldElement {HTMLElement}
+ * @returns {boolean}
+ */
+function isFormFieldElement(fieldElement) {
+	return fieldElement instanceof HTMLInputElement ||
+		fieldElement instanceof HTMLSelectElement ||
+		fieldElement instanceof HTMLTextAreaElement;
 }
 
 /**
@@ -266,145 +410,6 @@ function setCustomMessage(element, message) {
 	element.setCustomValidity(message || '');
 }
 
-/**
- * Validates form is valid and conditionally displays an error summary
- * @param formElement
- * @param validationOptions
- * @returns boolean
- */
-function validateAndReRender(formElement, validationOptions) {
-	const invalid = !formElement.checkValidity();
-	if (invalid) {
-		const errors = collectInvalidFields(formElement, validationOptions);
-		applyInlineFeedback(formElement, errors);
-		createErrorSummary(formElement, errors, validationOptions);
-
-		if (errors.length && validationOptions.focusFirstInvalid) {
-			const target = formElement.querySelector(`#${errors[0].id}`);
-			target?.focus();
-		}
-	} else {
-		document.querySelector(SUMMARY_SELECTOR)?.remove();
-	}
-
-	return !invalid;
-}
-
-/**
- * Initialise validation on a form element or selector.
- *
- * @param {string|HTMLFormElement} formOrSelector A form element or a selector resolving to one.
- * @param {O3ValidationOptions} [options] Validation configuration overrides.
- * @returns {HTMLFormElement|null} The initialised form element.
- */
-function initO3FormValidation(formOrSelector, options = {}) {
-	const formElement =
-		formOrSelector instanceof HTMLFormElement
-			? formOrSelector
-			: document.querySelector(formOrSelector);
-
-	if (!formElement || !(formElement instanceof HTMLFormElement)) {
-		throw new Error(
-			'initO3FormValidation must be passed a form element or selector resolving to a form.'
-		);
-	}
-	const validationOptions = Object.assign(
-		{
-			useBrowserReport: false,
-			errorSummary: true,
-			customMessages: undefined,
-			preventSubmit: true,
-			focusFirstInvalid: true,
-		},
-		options
-	);
-
-	if (validationOptions.useBrowserReport && validationOptions.preventSubmit) {
-		throw new Error('Cannot enable both useBrowserReport and preventSubmit.');
-	}
-
-	if (formState.has(formElement)) return formElement; // already initialised
-
-	const state = {validationOptions}; // future: may hold cached lastErrors etc.
-	formState.set(formElement, state);
-
-	formElement.addEventListener(
-		'invalid',
-		event => {
-			// suppress native tooltip when using custom summary
-			const current = formState.get(formElement);
-			if (!current) return;
-			if (isSubmitAttempted) {
-				const errors = collectInvalidFields(formElement, validationOptions);
-				applyInlineFeedback(formElement, errors);
-				createErrorSummary(formElement, errors, validationOptions);
-				if (current.validationOptions.errorSummary) {
-					event.preventDefault();
-				}
-				isSubmitAttempted = false;
-				console.log('submitted false on invalid event');
-			}
-		},
-		true
-	);
-
-	// progressive revalidation
-	const progressiveHandler = event => {
-		const current = formState.get(formElement);
-		if (!current) return;
-		const errors = collectInvalidFields(event.currentTarget, validationOptions);
-
-		const focussedErrors = isSubmitAttempted ? errors : errors.filter((error) => elementsPreviouslyFocussed.includes(error.id));
-
-		applyInlineFeedback(formElement, focussedErrors);
-	};
-
-	formElement.addEventListener('submit', (event) => {
-		isSubmitAttempted = true;
-
-		const ok = validateAndReRender(formElement, validationOptions);
-		if (!ok && validationOptions.preventSubmit) event.preventDefault();
-	});
-
-	formElement.addEventListener('pointerdown', event => {
-		const target = event.target.closest('button[type="submit"], input[type="submit"]');
-
-		const isSubmit =
-			target instanceof HTMLButtonElement
-				? target.type === 'submit'
-				: target instanceof HTMLInputElement && target.type === 'submit';
-
-		if (!isSubmit) return;
-		isSubmitAttempted = true;
-
-		const current = formState.get(formElement);
-		if (!current) return;
-		const {validationOptions} = current;
-
-		for (const fieldElement of formElement.elements) {
-			elementsPreviouslyFocussed.push(fieldElement.id);
-		}
-
-		const ok = validateAndReRender(formElement, validationOptions);
-		if (!ok && validationOptions.preventSubmit) event.preventDefault();
-	}, true);
-
-	formElement.addEventListener('input', progressiveHandler, true);
-	formElement.addEventListener('blur', progressiveHandler, true);
-
-	const fieldElements = Array.from(formElement.elements);
-
-	for (const fieldElement of fieldElements) {
-		if (!isFormFieldElement(fieldElement)) continue;
-
-		fieldElement.addEventListener('focusin', () => {
-			elementsPreviouslyFocussed.push(fieldElement.id);
-		});
-	}
-
-	return formElement;
-}
-
 /**
  * Destroy validation instance: remove listeners and summary.
  *

From 61b5ebb3a9e08c0648f11f9922b5069c04b19d87 Mon Sep 17 00:00:00 2001
From: "ben.freshwater" <ben.freshwater@ft.com>
Date: Thu, 8 Jan 2026 12:50:06 +0000
Subject: [PATCH 07/22] chore: refactor validation.js

---
 .../src/css/components/error-summary.css      |  2 +-
 components/o3-form/src/js/validation.js       | 27 +++++++++----------
 2 files changed, 14 insertions(+), 15 deletions(-)

diff --git a/components/o3-form/src/css/components/error-summary.css b/components/o3-form/src/css/components/error-summary.css
index 9828e1cb6b..5b060711f9 100644
--- a/components/o3-form/src/css/components/error-summary.css
+++ b/components/o3-form/src/css/components/error-summary.css
@@ -28,7 +28,7 @@
 		}
 	}
 
-	.o3-forms__error-summary__list {
+	.o3-form__error-summary__list {
 		list-style-type: none;
 		padding-left: 0;
 		margin-top: 0;
diff --git a/components/o3-form/src/js/validation.js b/components/o3-form/src/js/validation.js
index c7997a6597..19ca8d81e6 100644
--- a/components/o3-form/src/js/validation.js
+++ b/components/o3-form/src/js/validation.js
@@ -21,10 +21,10 @@
  * @property {('native'|'custom')} [source] Origin of message (native browser vs custom override).
  */
 
-const SUMMARY_SELECTOR = '.o3-form__error-summary';
 const SUMMARY_CLASS = 'o3-form__error-summary';
 const ERROR_INPUT_CLASS = 'o3-form-text-input--error';
-const ERROR_CHECK_CLASS = 'o3-form-input-error';
+const FORM_FEEDBACK_ERROR_CLASS = 'o3-form-feedback__error';
+const FORM_FIELD_CLASS = 'o3-form-field';
 
 /** Maintain internal state per form element */
 const formState = new WeakMap();
@@ -154,7 +154,6 @@ function initO3FormValidation(formOrSelector, options = {}) {
  * @returns {FieldError[]} An array of field error objects.
  */
 function collectInvalidFields(formElement, validationOptions) {
-	/** @type {HTMLElement[]} */
 	const elements = Array.from(formElement.elements);
 	/** @type {FieldError[]} */
 	const errors = [];
@@ -240,16 +239,16 @@ function applyInlineFeedback(formElement, errors) {
 		const [error] = errors.filter((error) => error.id === fieldElement.id);
 
 		if (!error) {
-			fieldElement.closest('.o3-form-field')?.querySelector('.o3-form-feedback__error')?.remove();
+			fieldElement.closest(`.${FORM_FIELD_CLASS}`)?.querySelector(`.${FORM_FEEDBACK_ERROR_CLASS}`)?.remove();
 			fieldElement.classList.remove(ERROR_INPUT_CLASS);
 		} else {
 			if (fieldElement.classList.contains('o3-form-text-input') && !fieldElement.classList.contains(ERROR_INPUT_CLASS)) {
 				fieldElement.classList.add(ERROR_INPUT_CLASS);
 			}
 
-			if (!fieldElement.parentElement.querySelector('.o3-form-feedback__error')) {//TODO: check if need to extract to const
+			if (!fieldElement.parentElement.querySelector(`.${FORM_FEEDBACK_ERROR_CLASS}`)) {
 				const errorMessageContainer = createFeedbackElement(error);
-				fieldElement.closest('.o3-form-field').appendChild(errorMessageContainer);//TODO: check if need to extract class to const
+				fieldElement.closest(`.${FORM_FIELD_CLASS}`).appendChild(errorMessageContainer);
 			}
 		}
 	}
@@ -275,7 +274,7 @@ function validateAndReRender(formElement, validationOptions) {
 			target?.focus();
 		}
 	} else {
-		document.querySelector(SUMMARY_SELECTOR)?.remove();
+		document.querySelector(`.${SUMMARY_CLASS}`)?.remove();
 	}
 
 	return !invalid;
@@ -289,10 +288,10 @@ function validateAndReRender(formElement, validationOptions) {
  */
 function createFeedbackElement(error) {
 	const errorMessageContainer = document.createElement('div');
-	errorMessageContainer.classList.add('o3-form-feedback', 'o3-form-feedback__error');//TODO: check if need to extract classes to const
+	errorMessageContainer.classList.add('o3-form-feedback', FORM_FEEDBACK_ERROR_CLASS);
 
 	const errorMessage = document.createElement('span');
-	errorMessage.classList.add('o3-form-feedback__error-message');//TODO: check if need to extract classes to const
+	errorMessage.classList.add(`${FORM_FEEDBACK_ERROR_CLASS}-message`);
 	errorMessage.innerText = error.message;
 	errorMessageContainer.appendChild(errorMessage);
 
@@ -309,7 +308,7 @@ function createFeedbackElement(error) {
 function createErrorSummary(formElement, errors, validationOptions) {
 	if (!validationOptions.errorSummary) return;
 
-	let summary = formElement.querySelector(SUMMARY_SELECTOR);
+	let summary = formElement.querySelector(`.${SUMMARY_CLASS}`);
 
 	if (!errors.length) {
 		if (summary) summary.remove();
@@ -326,10 +325,10 @@ function createErrorSummary(formElement, errors, validationOptions) {
 	summary.innerHTML = '';
 
 	const icon = document.createElement('span');
-	icon.className = 'o3-form__error-summary-icon';//TODO: check if we need to extract to const
+	icon.className = `${SUMMARY_CLASS}-icon`;
 
 	const headingWrapper = document.createElement('div');
-	headingWrapper.className = 'o3-form__error-summary__heading'; //TODO: check if we need to extract to const
+	headingWrapper.className = `${SUMMARY_CLASS}__heading`;
 	headingWrapper.setAttribute('aria-labelledby', 'error-summary-title');
 
 	const heading = document.createElement('span');
@@ -338,7 +337,7 @@ function createErrorSummary(formElement, errors, validationOptions) {
 	heading.textContent = 'Please correct these errors and try again.';
 
 	const list = document.createElement('ul');
-	list.className = 'o3-forms__error-summary__list o3-typography-body-small';
+	list.className = `${SUMMARY_CLASS}__list o3-typography-body-small`;
 
 	for (const error of errors) {
 		const listItem = document.createElement('li');
@@ -431,7 +430,7 @@ function destroyO3FormValidation(formOrSelector) {
 	const clone = formElement.cloneNode(true);
 	formElement.parentNode?.replaceChild(clone, formElement);
 
-	const summary = clone.querySelector(SUMMARY_SELECTOR);
+	const summary = clone.querySelector(`.${SUMMARY_CLASS}`);
 	summary?.remove();
 	formState.delete(clone); // new clone not initialised
 }

From 5f2031c7ec757acccca3fca35662a1fa4af1889a Mon Sep 17 00:00:00 2001
From: Ben Freshwater <ben.freshwater@ft.com>
Date: Fri, 9 Jan 2026 11:22:06 +0000
Subject: [PATCH 08/22] chore: Update
 components/o3-form/stories/formValidation.test.stories.tsx

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 components/o3-form/stories/formValidation.test.stories.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/components/o3-form/stories/formValidation.test.stories.tsx b/components/o3-form/stories/formValidation.test.stories.tsx
index e241bc7731..4584cb7572 100644
--- a/components/o3-form/stories/formValidation.test.stories.tsx
+++ b/components/o3-form/stories/formValidation.test.stories.tsx
@@ -67,7 +67,7 @@ export const FormValidationDisplaysElementErrorSummary = {
 		const thirdInput = within(canvas.getByTestId('third-input'));
 		const thirdInputElement = thirdInput.getByRole('textbox');
 
-		// Whenn clicking through the form.
+		// When clicking through the form.
 		await userEvent.click(firstInputElement);
 		await userEvent.click(secondInputElement);
 		await userEvent.click(thirdInputElement);

From d0e24358123621ee9a7d4d9dc881daa872f63ec0 Mon Sep 17 00:00:00 2001
From: Ben Freshwater <ben.freshwater@ft.com>
Date: Fri, 9 Jan 2026 11:22:32 +0000
Subject: [PATCH 09/22] chore: Update
 components/o3-form/stories/formValidation.test.stories.tsx

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 components/o3-form/stories/formValidation.test.stories.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/components/o3-form/stories/formValidation.test.stories.tsx b/components/o3-form/stories/formValidation.test.stories.tsx
index 4584cb7572..07bd6d643f 100644
--- a/components/o3-form/stories/formValidation.test.stories.tsx
+++ b/components/o3-form/stories/formValidation.test.stories.tsx
@@ -94,7 +94,7 @@ export const FormValidationDisplaysElementErrorSummary = {
 	},
 };
 
-export const FormValidtionDisplaysErrorSummary = {
+export const FormValidationDisplaysErrorSummary = {
 	parameters: {
 		design: {
 			type: 'figma',

From 5e28851e969bd8fd296f739509f6d607343f38ed Mon Sep 17 00:00:00 2001
From: Ben Freshwater <ben.freshwater@ft.com>
Date: Fri, 9 Jan 2026 11:22:47 +0000
Subject: [PATCH 10/22] chore: Update components/o3-form/src/js/validation.js

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 components/o3-form/src/js/validation.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/components/o3-form/src/js/validation.js b/components/o3-form/src/js/validation.js
index 19ca8d81e6..237e6fc3b4 100644
--- a/components/o3-form/src/js/validation.js
+++ b/components/o3-form/src/js/validation.js
@@ -283,7 +283,7 @@ function validateAndReRender(formElement, validationOptions) {
 /**
  * Creates feedback element
  *
- * @param {Error} error The error to create a feedback element for.
+ * @param {FieldError} error The error to create a feedback element for.
  * @returns {HTMLElement} A field error if invalid, otherwise null.
  */
 function createFeedbackElement(error) {

From 1d88bd45d28dfe19e02a540c6b4c5e8539fdf4e3 Mon Sep 17 00:00:00 2001
From: "ben.freshwater" <ben.freshwater@ft.com>
Date: Tue, 13 Jan 2026 10:40:12 +0000
Subject: [PATCH 11/22] fix: store form state in form WeakMap

---
 components/o3-form/src/js/validation.js | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/components/o3-form/src/js/validation.js b/components/o3-form/src/js/validation.js
index 237e6fc3b4..983fc411cd 100644
--- a/components/o3-form/src/js/validation.js
+++ b/components/o3-form/src/js/validation.js
@@ -28,8 +28,6 @@ const FORM_FIELD_CLASS = 'o3-form-field';
 
 /** Maintain internal state per form element */
 const formState = new WeakMap();
-const elementsPreviouslyFocussed = [];
-let isSubmitAttempted = false;
 
 /**
  * Initialise validation on a form element or selector.
@@ -66,7 +64,7 @@ function initO3FormValidation(formOrSelector, options = {}) {
 
 	if (formState.has(formElement)) return formElement; // already initialised
 
-	const state = {validationOptions}; // future: may hold cached lastErrors etc.
+	const state = {validationOptions, isSubmitAttempted: false, elementsPreviouslyFocussed: []}; // future: may hold cached lastErrors etc.
 	formState.set(formElement, state);
 
 	const progressiveHandler = event => {
@@ -74,7 +72,7 @@ function initO3FormValidation(formOrSelector, options = {}) {
 		if (!current) return;
 		const errors = collectInvalidFields(event.currentTarget, validationOptions);
 
-		const focussedErrors = isSubmitAttempted ? errors : errors.filter((error) => elementsPreviouslyFocussed.includes(error.id));
+		const focussedErrors = current.isSubmitAttempted ? errors : errors.filter((error) => current.elementsPreviouslyFocussed.includes(error.id));
 
 		applyInlineFeedback(formElement, focussedErrors);
 	};
@@ -85,21 +83,22 @@ function initO3FormValidation(formOrSelector, options = {}) {
 			// suppress native tooltip when using custom summary
 			const current = formState.get(formElement);
 			if (!current) return;
-			if (isSubmitAttempted) {
+			if (current.isSubmitAttempted) {
 				const errors = collectInvalidFields(formElement, validationOptions);
 				applyInlineFeedback(formElement, errors);
 				createErrorSummary(formElement, errors, validationOptions);
 				if (current.validationOptions.errorSummary) {
 					event.preventDefault();
 				}
-				isSubmitAttempted = false;
+				current.isSubmitAttempted = false;
 			}
 		},
 		true
 	);
 
 	formElement.addEventListener('submit', (event) => {
-		isSubmitAttempted = true;
+		const current = formState.get(formElement);
+		current.isSubmitAttempted = true;
 
 		const ok = validateAndReRender(formElement, validationOptions);
 
@@ -107,6 +106,7 @@ function initO3FormValidation(formOrSelector, options = {}) {
 	});
 
 	formElement.addEventListener('pointerdown', event => {
+		const current = formState.get(formElement);
 		const target = event.target.closest('button[type="submit"], input[type="submit"]');
 
 		const isSubmit =
@@ -115,14 +115,13 @@ function initO3FormValidation(formOrSelector, options = {}) {
 				: target instanceof HTMLInputElement && target.type === 'submit';
 
 		if (!isSubmit) return;
-		isSubmitAttempted = true;
 
-		const current = formState.get(formElement);
 		if (!current) return;
 		const {validationOptions} = current;
+		current.isSubmitAttempted = true;
 
 		for (const fieldElement of formElement.elements) {
-			elementsPreviouslyFocussed.push(fieldElement.id);
+			current.elementsPreviouslyFocussed.push(fieldElement.id);
 		}
 
 		const ok = validateAndReRender(formElement, validationOptions);
@@ -139,7 +138,8 @@ function initO3FormValidation(formOrSelector, options = {}) {
 		if (!isFormFieldElement(fieldElement)) continue;
 
 		fieldElement.addEventListener('focusin', () => {
-			elementsPreviouslyFocussed.push(fieldElement.id);
+			const current = formState.get(formElement);
+			current.elementsPreviouslyFocussed.push(fieldElement.id);
 		});
 	}
 

From 8c47f71c45b4688f9f2c0e96b1f8afa16586c0ec Mon Sep 17 00:00:00 2001
From: Ben Freshwater <ben.freshwater@ft.com>
Date: Tue, 13 Jan 2026 10:41:26 +0000
Subject: [PATCH 12/22] chore: Update components/o3-form/src/js/validation.js

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 components/o3-form/src/js/validation.js | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/components/o3-form/src/js/validation.js b/components/o3-form/src/js/validation.js
index 983fc411cd..8fdebc2fe5 100644
--- a/components/o3-form/src/js/validation.js
+++ b/components/o3-form/src/js/validation.js
@@ -246,9 +246,12 @@ function applyInlineFeedback(formElement, errors) {
 				fieldElement.classList.add(ERROR_INPUT_CLASS);
 			}
 
-			if (!fieldElement.parentElement.querySelector(`.${FORM_FEEDBACK_ERROR_CLASS}`)) {
+			const parentElement = fieldElement.parentElement;
+			const formFieldElement = fieldElement.closest(`.${FORM_FIELD_CLASS}`);
+
+			if (parentElement && formFieldElement && !parentElement.querySelector(`.${FORM_FEEDBACK_ERROR_CLASS}`)) {
 				const errorMessageContainer = createFeedbackElement(error);
-				fieldElement.closest(`.${FORM_FIELD_CLASS}`).appendChild(errorMessageContainer);
+				formFieldElement.appendChild(errorMessageContainer);
 			}
 		}
 	}

From d4e6986b9cb54d29d5118a7b9bf19f82b3e3d3cc Mon Sep 17 00:00:00 2001
From: "ben.freshwater" <ben.freshwater@ft.com>
Date: Tue, 13 Jan 2026 10:50:36 +0000
Subject: [PATCH 13/22] chore: use safe selectors

---
 components/o3-form/src/js/validation.js | 24 ++++++++++++++++++++----
 1 file changed, 20 insertions(+), 4 deletions(-)

diff --git a/components/o3-form/src/js/validation.js b/components/o3-form/src/js/validation.js
index 8fdebc2fe5..b2304ef2d4 100644
--- a/components/o3-form/src/js/validation.js
+++ b/components/o3-form/src/js/validation.js
@@ -257,6 +257,10 @@ function applyInlineFeedback(formElement, errors) {
 	}
 }
 
+function isCSSEscapeExist() {
+	return typeof CSS !== 'undefined' & typeof CSS.escape === 'function';
+}
+
 /**
  * Validates form is valid and conditionally displays an error summary
  * @param formElement
@@ -273,8 +277,17 @@ function validateAndReRender(formElement, validationOptions) {
 		createErrorSummary(formElement, errors, validationOptions);
 
 		if (errors.length && validationOptions.focusFirstInvalid) {
-			const target = formElement.querySelector(`#${errors[0].id}`);
-			target?.focus();
+			const firstErrorId = errors[0].id;
+			let target;
+
+			if(firstErrorId) {
+				if(isCSSEscapeExist()) {
+					target = formElement.querySelector(`#${CSS.escape(firstErrorId)}`);
+				} else {
+					const safeId = String(firstErrorId).replace(/"/g, '\\"');
+					target = formElement.querySelector(`[id="${safeId}"]`);
+				}
+			}
 		}
 	} else {
 		document.querySelector(`.${SUMMARY_CLASS}`)?.remove();
@@ -348,7 +361,7 @@ function createErrorSummary(formElement, errors, validationOptions) {
 		if (error.id) {
 			const link = document.createElement('a');
 			link.className = 'o3-typography-link';
-			link.href = `#${error.id}`;
+			link.href = `#${encodeURIComponent(error.id)}`;
 			link.textContent = error.fieldName;
 			listItem.appendChild(link);
 
@@ -382,7 +395,10 @@ function deriveFieldName(element) {
 	if (!element) return 'Field';
 
 	if (element.id) {
-		const label = element.form?.querySelector(`label[for="${element.id}"]`);
+		const escapeId = isCSSEscapeExist() ? CSS.escape(element.id) : element.id.replace(/"/g, '\\"');
+
+		const label = element.form?.querySelector(`label[for="${escapeId}"]`);
+
 		if (label && label.textContent) return label.textContent.trim();
 	}
 

From b5731083a9f904e9be936942f829db0e3789f7ef Mon Sep 17 00:00:00 2001
From: "ben.freshwater" <ben.freshwater@ft.com>
Date: Tue, 13 Jan 2026 10:56:50 +0000
Subject: [PATCH 14/22] chore: improve styling of validation form

---
 components/o3-form/stories/FormValidationHtml.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/components/o3-form/stories/FormValidationHtml.tsx b/components/o3-form/stories/FormValidationHtml.tsx
index 5b3bcdea51..be9e6630bd 100644
--- a/components/o3-form/stories/FormValidationHtml.tsx
+++ b/components/o3-form/stories/FormValidationHtml.tsx
@@ -64,7 +64,7 @@ export const FormValidationHtml = () => {
 					type="text"
 				/>
 			</div>
-			<input data-testid="submit-button" className="o3-button o3-button--primary" type="submit" value="Submit"/>
+			<input data-testid="submit-button" className="o3-button o3-button--primary" type="submit" value="Submit" style={{'margin-top': '12px'}}/>
 		</form>
 	)
 }

From 3e5600c6b15021073663ed590e4449716023e893 Mon Sep 17 00:00:00 2001
From: "ben.freshwater" <ben.freshwater@ft.com>
Date: Tue, 13 Jan 2026 10:58:06 +0000
Subject: [PATCH 15/22] chore: improve typing of validateAndReRender

---
 components/o3-form/src/js/validation.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/components/o3-form/src/js/validation.js b/components/o3-form/src/js/validation.js
index b2304ef2d4..a97703d70c 100644
--- a/components/o3-form/src/js/validation.js
+++ b/components/o3-form/src/js/validation.js
@@ -263,8 +263,8 @@ function isCSSEscapeExist() {
 
 /**
  * Validates form is valid and conditionally displays an error summary
- * @param formElement
- * @param validationOptions
+ * @param {HTMLFontElement} formElement
+ * @param {O3ValidationOptions} validationOptions
  * @returns boolean
  */
 function validateAndReRender(formElement, validationOptions) {

From 3c8fc6cb73c31cabcb02038fa9a424d944987968 Mon Sep 17 00:00:00 2001
From: Ben Freshwater <ben.freshwater@ft.com>
Date: Tue, 13 Jan 2026 11:02:47 +0000
Subject: [PATCH 16/22] chore: Potential fix for code scanning alert no. 28:
 Incomplete string escaping or encoding

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
---
 components/o3-form/src/js/validation.js | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/components/o3-form/src/js/validation.js b/components/o3-form/src/js/validation.js
index a97703d70c..55bd12093e 100644
--- a/components/o3-form/src/js/validation.js
+++ b/components/o3-form/src/js/validation.js
@@ -284,7 +284,9 @@ function validateAndReRender(formElement, validationOptions) {
 				if(isCSSEscapeExist()) {
 					target = formElement.querySelector(`#${CSS.escape(firstErrorId)}`);
 				} else {
-					const safeId = String(firstErrorId).replace(/"/g, '\\"');
+					const safeId = String(firstErrorId)
+						.replace(/\\/g, '\\\\')
+						.replace(/"/g, '\\"');
 					target = formElement.querySelector(`[id="${safeId}"]`);
 				}
 			}

From c12ef9742bfbf4a6fae778ccac98529ceff62292 Mon Sep 17 00:00:00 2001
From: "ben.freshwater" <ben.freshwater@ft.com>
Date: Tue, 13 Jan 2026 11:10:41 +0000
Subject: [PATCH 17/22] chore: use safer css selectors

---
 components/o3-form/src/js/validation.js           | 2 +-
 components/o3-form/stories/FormValidationHtml.tsx | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/components/o3-form/src/js/validation.js b/components/o3-form/src/js/validation.js
index 55bd12093e..f0ca1ba177 100644
--- a/components/o3-form/src/js/validation.js
+++ b/components/o3-form/src/js/validation.js
@@ -397,7 +397,7 @@ function deriveFieldName(element) {
 	if (!element) return 'Field';
 
 	if (element.id) {
-		const escapeId = isCSSEscapeExist() ? CSS.escape(element.id) : element.id.replace(/"/g, '\\"');
+		const escapeId = isCSSEscapeExist() ? CSS.escape(element.id) : element.id.replace(/"/g, '\\"').replace(/"/g, '\\"');;
 
 		const label = element.form?.querySelector(`label[for="${escapeId}"]`);
 
diff --git a/components/o3-form/stories/FormValidationHtml.tsx b/components/o3-form/stories/FormValidationHtml.tsx
index be9e6630bd..771cbbfcc0 100644
--- a/components/o3-form/stories/FormValidationHtml.tsx
+++ b/components/o3-form/stories/FormValidationHtml.tsx
@@ -64,7 +64,7 @@ export const FormValidationHtml = () => {
 					type="text"
 				/>
 			</div>
-			<input data-testid="submit-button" className="o3-button o3-button--primary" type="submit" value="Submit" style={{'margin-top': '12px'}}/>
+			<input data-testid="submit-button" className="o3-button o3-button--primary" type="submit" value="Submit" style={{'marginTop': '12px'}}/>
 		</form>
 	)
 }

From 0fb25419538136dc71985d868d05565676bcfe89 Mon Sep 17 00:00:00 2001
From: "ben.freshwater" <ben.freshwater@ft.com>
Date: Tue, 13 Jan 2026 11:15:26 +0000
Subject: [PATCH 18/22] chore: will you ever be happy copilot?

---
 components/o3-form/src/js/validation.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/components/o3-form/src/js/validation.js b/components/o3-form/src/js/validation.js
index f0ca1ba177..d557ce681b 100644
--- a/components/o3-form/src/js/validation.js
+++ b/components/o3-form/src/js/validation.js
@@ -397,7 +397,7 @@ function deriveFieldName(element) {
 	if (!element) return 'Field';
 
 	if (element.id) {
-		const escapeId = isCSSEscapeExist() ? CSS.escape(element.id) : element.id.replace(/"/g, '\\"').replace(/"/g, '\\"');;
+		const escapeId = isCSSEscapeExist() ? CSS.escape(element.id) : element.id.replace(/\\/g, '\\\\"').replace(/"/g, '\\"');;
 
 		const label = element.form?.querySelector(`label[for="${escapeId}"]`);
 

From 6cc2d388929f83d3475a1f7803eb61e147a18017 Mon Sep 17 00:00:00 2001
From: "ben.freshwater" <ben.freshwater@ft.com>
Date: Tue, 13 Jan 2026 16:24:38 +0000
Subject: [PATCH 19/22] chore: fix tests breaking in CI

The issue came down to browsers rendering different text for the same errors. Short term fix for now is to assert on both error messages
---
 .../stories/formValidation.test.stories.tsx   | 45 +++++++++++--------
 1 file changed, 26 insertions(+), 19 deletions(-)

diff --git a/components/o3-form/stories/formValidation.test.stories.tsx b/components/o3-form/stories/formValidation.test.stories.tsx
index 07bd6d643f..a39059b393 100644
--- a/components/o3-form/stories/formValidation.test.stories.tsx
+++ b/components/o3-form/stories/formValidation.test.stories.tsx
@@ -73,15 +73,15 @@ export const FormValidationDisplaysElementErrorSummary = {
 		await userEvent.click(thirdInputElement);
 
 		// It should highlight the first input field as invalid
-		expect(firstInput.queryByText('Please fill in this field.')).toBeInTheDocument();
+		expect(firstInput.queryByText(getInlineErrorText(), {selector: ".o3-form-feedback__error-message"})).toBeInTheDocument();
 		expect(firstInputElement.classList).toContain('o3-form-text-input--error');
 
 		// It should highlight the second input field as invalid
-		expect(secondInput.queryByText('Please fill in this field.')).toBeInTheDocument();
+		expect(secondInput.queryByText(getInlineErrorText(), {selector: ".o3-form-feedback__error-message"})).toBeInTheDocument();
 		expect(secondInputElement.classList).toContain('o3-form-text-input--error');
 
 		// It should not highlight the third input field as invalid
-		expect(thirdInput.queryByText('Please fill in this field.')).not.toBeInTheDocument();
+		expect(thirdInput.queryByText(getInlineErrorText(), {selector: ".o3-form-feedback__error-message"})).not.toBeInTheDocument();
 		expect(thirdInputElement.classList).not.toContain('o3-form-text-input--error');
 
 		// When correcting an error
@@ -89,7 +89,7 @@ export const FormValidationDisplaysElementErrorSummary = {
 		await userEvent.type(firstInputElement, 'My resolving text');
 
 		// It should not highlight the first input field as invalid
-		expect(firstInput.queryByText('Please fill in this field.')).not.toBeInTheDocument();
+		expect(firstInput.queryByText(getInlineErrorText(), {selector: ".o3-form-feedback__error-message"})).not.toBeInTheDocument();
 		expect(firstInputElement.classList).not.toContain('o3-form-text-input--error');
 	},
 };
@@ -111,6 +111,9 @@ export const FormValidationDisplaysErrorSummary = {
 		) as HTMLFormElement | null;
 
 		if (form) {
+			form.addEventListener('submit', (event) => {
+				event.preventDefault();
+			});
 			initO3FormValidation(form);
 		} else {
 			return false;
@@ -120,13 +123,17 @@ export const FormValidationDisplaysErrorSummary = {
 		const submitButton = canvas.getByTestId('submit-button');
 		await userEvent.click(submitButton);
 
+		const errorSummary = canvasElement.querySelector('.o3-form__error-summary');
 		// It should render an error summary
-		expect(canvasElement.querySelector('.o3-form__error-summary')).toBeInTheDocument();
+		expect(errorSummary).toBeInTheDocument();
+
 
 		// It should list all erroring fields with a reason
-		expect(canvas.queryByText(getErrorSummaryLineItemText('First name'))).toBeInTheDocument();
-		expect(canvas.queryByText(getErrorSummaryLineItemText('Last name'))).toBeInTheDocument();
-		expect(canvas.queryByText(getErrorSummaryLineItemText('CVV code'))).toBeInTheDocument();
+		const summaryWithin = within(errorSummary);
+
+		await summaryWithin.findByText(getErrorSummaryLineItemText('First name'));
+		await summaryWithin.findByText(getErrorSummaryLineItemText('Last name'));
+		await summaryWithin.findByText(getErrorSummaryLineItemText('CVV code'));
 
 		const firstInput = within(canvas.getByTestId('first-input'));
 		const firstInputElement = firstInput.getByRole('textbox');
@@ -138,15 +145,15 @@ export const FormValidationDisplaysErrorSummary = {
 		const thirdInputElement = thirdInput.getByRole('textbox');
 
 		// It should highlight the first input field as invalid
-		expect(firstInput.queryByText('Please fill in this field.')).toBeInTheDocument();
+		expect(firstInput.queryByText(getInlineErrorText(), {selector: ".o3-form-feedback__error-message"})).toBeInTheDocument();
 		expect(firstInputElement.classList).toContain('o3-form-text-input--error');
 
 		// It should highlight the second input field as invalid
-		expect(secondInput.queryByText('Please fill in this field.')).toBeInTheDocument();
+		expect(secondInput.queryByText(getInlineErrorText(), {selector: ".o3-form-feedback__error-message"})).toBeInTheDocument();
 		expect(secondInputElement.classList).toContain('o3-form-text-input--error');
 
 		// It should not highlight the third input field as invalid
-		expect(thirdInput.queryByText('Please fill in this field.')).toBeInTheDocument();
+		expect(thirdInput.queryByText(getInlineErrorText(), {selector: ".o3-form-feedback__error-message"})).toBeInTheDocument();
 		expect(thirdInputElement.classList).toContain('o3-form-text-input--error');
 
 		// When resolving one field
@@ -159,21 +166,18 @@ export const FormValidationDisplaysErrorSummary = {
 		expect(canvas.queryByText(getErrorSummaryLineItemText('CVV code'))).toBeInTheDocument();
 
 		// It should not highlight the first input field as invalid
-		expect(firstInput.queryByText('Please fill in this field.')).not.toBeInTheDocument();
+		expect(firstInput.queryByText(getInlineErrorText(), {selector: ".o3-form-feedback__error-message"})).not.toBeInTheDocument();
 		expect(firstInputElement.classList).not.toContain('o3-form-text-input--error');
 
 		// It should highlight the second input field as invalid
-		expect(secondInput.queryByText('Please fill in this field.')).toBeInTheDocument();
+		expect(secondInput.queryByText(getInlineErrorText(), {selector: ".o3-form-feedback__error-message"})).toBeInTheDocument();
 		expect(secondInputElement.classList).toContain('o3-form-text-input--error');
 
 		// It should not highlight the third input field as invalid
-		expect(thirdInput.queryByText('Please fill in this field.')).toBeInTheDocument();
+		expect(thirdInput.queryByText(getInlineErrorText(), {selector: ".o3-form-feedback__error-message"})).toBeInTheDocument();
 		expect(thirdInputElement.classList).toContain('o3-form-text-input--error');
 
 		// When resolving all other fields.
-		form.addEventListener('submit', (event) => {
-			event.preventDefault();
-		});
 		await userEvent.type(secondInputElement, 'My resolving text');
 		await userEvent.type(thirdInputElement, 'My resolving text');
 		await userEvent.click(submitButton);
@@ -183,9 +187,12 @@ export const FormValidationDisplaysErrorSummary = {
 	},
 };
 
-const getErrorSummaryLineItemText = (expectedText: string) => (text: string, element: HTMLElement) => {
-	return element.textContent === `${expectedText}: Please fill in this field.`;
+const getErrorSummaryLineItemText = (expectedText: string) => (_: string, element: HTMLElement) => {
+	return element.textContent === `${expectedText}: Please fill out this field.` || element.textContent === `${expectedText}: Please fill in this field.`;
+}
 
+const getInlineErrorText = () => (_: string, element: HTMLElement) => {
+	return element.textContent === `Please fill out this field.` || element.textContent === `Please fill in this field.`;
 }
 
 export default meta;

From f969cbf9f3743ab5bb49797199329f0cc8f79463 Mon Sep 17 00:00:00 2001
From: Ben Freshwater <ben.freshwater@ft.com>
Date: Tue, 13 Jan 2026 16:39:32 +0000
Subject: [PATCH 20/22] Update components/o3-form/src/js/validation.js

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 components/o3-form/src/js/validation.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/components/o3-form/src/js/validation.js b/components/o3-form/src/js/validation.js
index d557ce681b..f933c23f1c 100644
--- a/components/o3-form/src/js/validation.js
+++ b/components/o3-form/src/js/validation.js
@@ -397,7 +397,7 @@ function deriveFieldName(element) {
 	if (!element) return 'Field';
 
 	if (element.id) {
-		const escapeId = isCSSEscapeExist() ? CSS.escape(element.id) : element.id.replace(/\\/g, '\\\\"').replace(/"/g, '\\"');;
+		const escapeId = isCSSEscapeExist() ? CSS.escape(element.id) : element.id.replace(/\\/g, '\\\\"').replace(/"/g, '\\"');
 
 		const label = element.form?.querySelector(`label[for="${escapeId}"]`);
 

From 5af75e2ca4cb63bb0583da5bbe419866063f98cb Mon Sep 17 00:00:00 2001
From: Ben Freshwater <ben.freshwater@ft.com>
Date: Tue, 13 Jan 2026 16:39:46 +0000
Subject: [PATCH 21/22] chore: Update components/o3-form/src/js/validation.js

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 components/o3-form/src/js/validation.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/components/o3-form/src/js/validation.js b/components/o3-form/src/js/validation.js
index f933c23f1c..f45b2b9183 100644
--- a/components/o3-form/src/js/validation.js
+++ b/components/o3-form/src/js/validation.js
@@ -263,7 +263,7 @@ function isCSSEscapeExist() {
 
 /**
  * Validates form is valid and conditionally displays an error summary
- * @param {HTMLFontElement} formElement
+ * @param {HTMLFormElement} formElement
  * @param {O3ValidationOptions} validationOptions
  * @returns boolean
  */

From 2d27dd0a86189f9a10e734d1b4f4b0c80d1d8adb Mon Sep 17 00:00:00 2001
From: Ben Freshwater <ben.freshwater@ft.com>
Date: Tue, 13 Jan 2026 16:39:55 +0000
Subject: [PATCH 22/22] chore: Update components/o3-form/src/js/validation.js

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 components/o3-form/src/js/validation.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/components/o3-form/src/js/validation.js b/components/o3-form/src/js/validation.js
index f45b2b9183..5ce25b5c51 100644
--- a/components/o3-form/src/js/validation.js
+++ b/components/o3-form/src/js/validation.js
@@ -258,7 +258,7 @@ function applyInlineFeedback(formElement, errors) {
 }
 
 function isCSSEscapeExist() {
-	return typeof CSS !== 'undefined' & typeof CSS.escape === 'function';
+	return typeof CSS !== 'undefined' && typeof CSS.escape === 'function';
 }
 
 /**