From 3b2012e7042b638b295f6313c86ae54a40f45be5 Mon Sep 17 00:00:00 2001
From: simoleo89 <simoleo89@gmail.com>
Date: Wed, 2 Sep 2026 19:38:38 +0200
Subject: [PATCH] feat(housekeeping): retain invalid command input

---
 .../content/pages/content-command-form.tsx    | 307 ++++++++++++------
 .../content/pages/content-pages.test.tsx      | 125 ++++++-
 2 files changed, 326 insertions(+), 106 deletions(-)

diff --git a/src/features/housekeeping/domains/content/pages/content-command-form.tsx b/src/features/housekeeping/domains/content/pages/content-command-form.tsx
index 8871d39a..fe02a7d7 100644
--- a/src/features/housekeeping/domains/content/pages/content-command-form.tsx
+++ b/src/features/housekeeping/domains/content/pages/content-command-form.tsx
@@ -99,14 +99,43 @@ function parseField(field: ContentCommandField, formData: FormData): unknown {
 	);
 }
 
-const initialState: HousekeepingResult<unknown> | null = null;
+export interface ContentCommandFormState {
+	readonly result: HousekeepingResult<unknown> | null;
+	readonly values: Readonly<Record<string, string>>;
+}
+
+const initialState: ContentCommandFormState = { result: null, values: {} };
+
+function readSubmittedValues(
+	fields: readonly ContentCommandField[],
+	requiresReason: boolean,
+	formData: FormData,
+): Readonly<Record<string, string>> {
+	const values: Record<string, string> = {};
+	for (const field of fields) {
+		if (field.type === "file") continue;
+		const value = formData.get(field.name);
+		if (typeof value === "string") values[field.name] = value;
+	}
+	if (requiresReason) {
+		const reason = formData.get("reason");
+		if (typeof reason === "string") values.reason = reason;
+	}
+	return values;
+}
 
 export async function submitContentCommandForm(
 	configuration: ContentCommandSubmission,
-	_previous: HousekeepingResult<unknown> | null,
+	_previous: ContentCommandFormState | null,
 	formData: FormData,
-): Promise<HousekeepingResult<unknown>> {
-	const submittedFields = (configuration.fields ?? []).flatMap((field) => {
+): Promise<ContentCommandFormState> {
+	const fields = configuration.fields ?? [];
+	const submittedValues = readSubmittedValues(
+		fields,
+		configuration.requiresReason ?? false,
+		formData,
+	);
+	const submittedFields = fields.flatMap((field) => {
 		const value = parseField(field, formData);
 		return value === OMIT_FIELD ? [] : [[field.name, value] as const];
 	});
@@ -121,11 +150,31 @@ export async function submitContentCommandForm(
 	const { executeHousekeepingCommand } = await import(
 		"@/actions/housekeeping-command"
 	);
-	return executeHousekeepingCommand({
+	const result = await executeHousekeepingCommand({
 		commandId: configuration.commandId,
 		input,
 		...(configuration.requiresReason ? { reason } : {}),
 	});
+	return { result, values: result.ok ? {} : submittedValues };
+}
+
+export function ContentCommandFieldError({
+	result,
+	fieldName,
+	errorId,
+}: {
+	readonly result: HousekeepingResult<unknown>;
+	readonly fieldName: string;
+	readonly errorId: string;
+}) {
+	if (result.ok) return null;
+	const messages = result.error.fieldErrors?.[fieldName];
+	if (!messages || messages.length === 0) return null;
+	return (
+		<p id={errorId} role="alert" className="text-xs text-[var(--admin-error)]">
+			{messages.join(" · ")}
+		</p>
+	);
 }
 
 export function ContentCommandForm({
@@ -136,7 +185,7 @@ export function ContentCommandForm({
 	requiresReason = false,
 }: ContentCommandFormProps) {
 	const formId = useId();
-	const [result, submit, pending] = useActionState(
+	const [state, submit, pending] = useActionState(
 		submitContentCommandForm.bind(null, {
 			commandId,
 			input,
@@ -145,121 +194,168 @@ export function ContentCommandForm({
 		}),
 		initialState,
 	);
+	const result = state.result;
+	const retainedValues = result && !result.ok ? state.values : {};
+	const remountKey = `${formId}-${result?.correlationId ?? "initial"}`;
+	const reasonErrorId = `${formId}-reason-error`;
+	const hasReasonError =
+		!result || result.ok
+			? false
+			: Boolean(result.error.fieldErrors?.reason?.length);
+
 	return (
 		<form
+			key={remountKey}
 			action={submit}
 			data-housekeeping-command={commandId}
 			className="space-y-3 rounded border border-[var(--admin-border)] p-3"
 		>
-			{fields.map((field) => (
-				<label
-					key={field.name}
-					htmlFor={`${formId}-${field.name}`}
-					className="block text-sm"
-				>
-					{field.type === "checkbox" && field.allowUnchanged ? (
-						<>
-							{field.label}
-							<select
-								id={`${formId}-${field.name}`}
-								name={field.name}
-								defaultValue=""
-								className="mt-1 block w-full"
-							>
-								<option value="">No change</option>
-								<option value="true">Enabled</option>
-								<option value="false">Disabled</option>
-							</select>
-						</>
-					) : field.type === "checkbox" ? (
-						<>
-							<input
-								id={`${formId}-${field.name}`}
-								name={field.name}
-								type="checkbox"
-								defaultChecked={field.defaultValue === true}
-							/>{" "}
-							{field.label}
-						</>
-					) : field.type === "select" ? (
-						<>
-							{field.label}
-							<select
-								id={`${formId}-${field.name}`}
-								name={field.name}
-								defaultValue={
-									typeof field.defaultValue === "boolean"
-										? undefined
-										: field.defaultValue
-								}
-								required={field.required}
-								className="mt-1 block w-full"
-							>
-								{field.required ? null : <option value="">No change</option>}
-								{field.options?.map((option) => (
-									<option key={option.value} value={option.value}>
-										{option.label}
-									</option>
-								))}
-							</select>
-						</>
-					) : field.type === "textarea" || field.type === "json" ? (
-						<>
-							{field.label}
-							<textarea
-								id={`${formId}-${field.name}`}
-								name={field.name}
-								defaultValue={
-									typeof field.defaultValue === "boolean"
-										? undefined
-										: field.defaultValue
-								}
-								required={field.required}
-								maxLength={field.maxLength}
-								className="mt-1 block w-full"
+			{fields.map((field) => {
+				const retainedValue = retainedValues[field.name];
+				const errorId = `${formId}-${field.name}-error`;
+				const hasError =
+					!result?.ok &&
+					Boolean(result?.error.fieldErrors?.[field.name]?.length);
+				const fieldErrorProps = hasError
+					? { "aria-invalid": true, "aria-describedby": errorId }
+					: {};
+				return (
+					<label
+						key={field.name}
+						htmlFor={`${formId}-${field.name}`}
+						className="block text-sm"
+					>
+						{field.type === "checkbox" && field.allowUnchanged ? (
+							<>
+								{field.label}
+								<select
+									id={`${formId}-${field.name}`}
+									name={field.name}
+									defaultValue={retainedValue ?? ""}
+									className="mt-1 block w-full"
+									{...fieldErrorProps}
+								>
+									<option value="">No change</option>
+									<option value="true">Enabled</option>
+									<option value="false">Disabled</option>
+								</select>
+							</>
+						) : field.type === "checkbox" ? (
+							<>
+								<input
+									id={`${formId}-${field.name}`}
+									name={field.name}
+									type="checkbox"
+									defaultChecked={
+										retainedValue === "on" ||
+										(retainedValue === undefined && field.defaultValue === true)
+									}
+									{...fieldErrorProps}
+								/>{" "}
+								{field.label}
+							</>
+						) : field.type === "select" ? (
+							<>
+								{field.label}
+								<select
+									id={`${formId}-${field.name}`}
+									name={field.name}
+									defaultValue={
+										retainedValue ??
+										(typeof field.defaultValue === "boolean"
+											? undefined
+											: field.defaultValue)
+									}
+									required={field.required}
+									className="mt-1 block w-full"
+									{...fieldErrorProps}
+								>
+									{field.required ? null : <option value="">No change</option>}
+									{field.options?.map((option) => (
+										<option key={option.value} value={option.value}>
+											{option.label}
+										</option>
+									))}
+								</select>
+							</>
+						) : field.type === "textarea" || field.type === "json" ? (
+							<>
+								{field.label}
+								<textarea
+									id={`${formId}-${field.name}`}
+									name={field.name}
+									defaultValue={
+										retainedValue ??
+										(typeof field.defaultValue === "boolean"
+											? undefined
+											: field.defaultValue)
+									}
+									required={field.required}
+									maxLength={field.maxLength}
+									className="mt-1 block w-full"
+									{...fieldErrorProps}
+								/>
+							</>
+						) : (
+							<>
+								{field.label}
+								<input
+									id={`${formId}-${field.name}`}
+									name={field.name}
+									type={
+										field.type === "number"
+											? "number"
+											: field.type === "datetime-local"
+												? "datetime-local"
+												: field.type === "file"
+													? "file"
+													: "text"
+									}
+									defaultValue={
+										field.type === "file" ||
+										typeof field.defaultValue === "boolean"
+											? undefined
+											: (retainedValue ?? field.defaultValue)
+									}
+									required={field.required}
+									min={field.min}
+									max={field.max}
+									maxLength={field.maxLength}
+									className="mt-1 block w-full"
+									{...fieldErrorProps}
+								/>
+							</>
+						)}
+						{result ? (
+							<ContentCommandFieldError
+								result={result}
+								fieldName={field.name}
+								errorId={errorId}
 							/>
-						</>
-					) : (
-						<>
-							{field.label}
-							<input
-								id={`${formId}-${field.name}`}
-								name={field.name}
-								type={
-									field.type === "number"
-										? "number"
-										: field.type === "datetime-local"
-											? "datetime-local"
-											: field.type === "file"
-												? "file"
-												: "text"
-								}
-								defaultValue={
-									field.type === "file" ||
-									typeof field.defaultValue === "boolean"
-										? undefined
-										: field.defaultValue
-								}
-								required={field.required}
-								min={field.min}
-								max={field.max}
-								maxLength={field.maxLength}
-								className="mt-1 block w-full"
-							/>
-						</>
-					)}
-				</label>
-			))}
+						) : null}
+					</label>
+				);
+			})}
 			{requiresReason ? (
 				<label htmlFor={`${formId}-reason`} className="block text-sm">
 					Reason
 					<textarea
 						id={`${formId}-reason`}
 						name="reason"
+						defaultValue={retainedValues.reason}
 						required
 						maxLength={1000}
 						className="mt-1 block w-full"
+						aria-invalid={hasReasonError || undefined}
+						aria-describedby={hasReasonError ? reasonErrorId : undefined}
 					/>
+					{result ? (
+						<ContentCommandFieldError
+							result={result}
+							fieldName="reason"
+							errorId={reasonErrorId}
+						/>
+					) : null}
 				</label>
 			) : null}
 			<button type="submit" disabled={pending}>
@@ -267,7 +363,8 @@ export function ContentCommandForm({
 			</button>
 			{result ? (
 				<p role="status" className="text-xs text-[var(--admin-text-muted)]">
-					{result.ok ? "Completed" : "Failed"} ({result.correlationId})
+					{result.ok ? "Completed" : result.error.messageKey} (
+					{result.correlationId})
 				</p>
 			) : null}
 		</form>
diff --git a/src/features/housekeeping/domains/content/pages/content-pages.test.tsx b/src/features/housekeeping/domains/content/pages/content-pages.test.tsx
index af376659..376a2cfc 100644
--- a/src/features/housekeeping/domains/content/pages/content-pages.test.tsx
+++ b/src/features/housekeeping/domains/content/pages/content-pages.test.tsx
@@ -9,6 +9,7 @@ import {
 } from "../../../foundation/contracts";
 import { ContentBrandPage } from "./brand";
 import {
+	ContentCommandFieldError,
 	ContentCommandForm,
 	submitContentCommandForm,
 } from "./content-command-form";
@@ -125,6 +126,128 @@ describe.each(cases)("Content %s page", (kind, Component, editPermission) => {
 
 describe("Content actionable form wiring", () => {
 	beforeEach(() => vi.clearAllMocks());
+
+	it("retains configured string values after validation and excludes files", async () => {
+		vi.mocked(executeHousekeepingCommand).mockResolvedValue(
+			fail("VALIDATION", "errors.housekeeping.validation", "poll-validation", {
+				title: ["errors.validation.invalid"],
+			}),
+		);
+		const formData = new FormData();
+		formData.set("title", "Draft title");
+		formData.set("cover", new Blob(["asset"]), "cover.png");
+
+		const state = await submitContentCommandForm(
+			{
+				commandId: "content.engagement.poll.change",
+				input: { action: "create" },
+				fields: [
+					{ name: "title", label: "Title", type: "text", required: true },
+					{ name: "cover", label: "Cover", type: "file" },
+				],
+			},
+			null,
+			formData,
+		);
+
+		expect(state).toMatchObject({
+			result: { ok: false, error: { code: "VALIDATION" } },
+			values: { title: "Draft title" },
+		});
+		expect(state).not.toHaveProperty("values.cover");
+	});
+
+	it("retains submitted fields and reason after a conflict", async () => {
+		vi.mocked(executeHousekeepingCommand).mockResolvedValue(
+			fail("CONFLICT", "errors.housekeeping.conflict", "poll-conflict"),
+		);
+		const formData = new FormData();
+		formData.set("title", "Conflicting draft");
+		formData.set("reason", "Keep the local wording");
+
+		const state = await submitContentCommandForm(
+			{
+				commandId: "content.engagement.poll.change",
+				input: { action: "update", id: "41" },
+				fields: [{ name: "title", label: "Title", type: "text" }],
+				requiresReason: true,
+			},
+			null,
+			formData,
+		);
+
+		expect(state).toMatchObject({
+			result: { ok: false, error: { code: "CONFLICT" } },
+			values: {
+				title: "Conflicting draft",
+				reason: "Keep the local wording",
+			},
+		});
+	});
+
+	it("clears retained values after a successful command", async () => {
+		vi.mocked(executeHousekeepingCommand).mockResolvedValue(
+			ok({ before: null, after: { id: "41" } }, "poll-success"),
+		);
+		const formData = new FormData();
+		formData.set("title", "Published poll");
+
+		const state = await submitContentCommandForm(
+			{
+				commandId: "content.engagement.poll.change",
+				input: { action: "create" },
+				fields: [{ name: "title", label: "Title", type: "text" }],
+			},
+			null,
+			formData,
+		);
+
+		expect(state).toMatchObject({ result: { ok: true }, values: {} });
+	});
+
+	it("renders an accessible stable field error", () => {
+		const html = renderToStaticMarkup(
+			<ContentCommandFieldError
+				result={fail(
+					"VALIDATION",
+					"errors.housekeeping.validation",
+					"poll-validation",
+					{ title: ["errors.validation.invalid"] },
+				)}
+				fieldName="title"
+				errorId="poll-validation-title-error"
+			/>,
+		);
+
+		expect(html).toContain('id="poll-validation-title-error"');
+		expect(html).toContain('role="alert"');
+		expect(html).toContain("errors.validation.invalid");
+	});
+
+	it("generates distinct control IDs for multiple forms on one page", () => {
+		const html = renderToStaticMarkup(
+			<>
+				<ContentCommandForm
+					commandId="content.engagement.poll.change"
+					buttonLabel="Create poll"
+					input={{ action: "create" }}
+					fields={[{ name: "title", label: "Title", type: "text" }]}
+				/>
+				<ContentCommandForm
+					commandId="content.engagement.poll.change"
+					buttonLabel="Update poll"
+					input={{ action: "update", id: "41" }}
+					fields={[{ name: "title", label: "Title", type: "text" }]}
+				/>
+			</>,
+		);
+		const titleIds = [...html.matchAll(/id="([^"]+-title)"/gu)].map(
+			(match) => match[1],
+		);
+
+		expect(titleIds).toHaveLength(2);
+		expect(new Set(titleIds).size).toBe(2);
+	});
 	it("renders and submits native event date-time fields", async () => {
 		const html = renderToStaticMarkup(
 			<ContentCommandForm
@@ -244,7 +367,7 @@ describe("Content actionable form wiring", () => {
 			},
 			reason: "r".repeat(1000),
 		});
-		expect(result).toMatchObject({ ok: true });
+		expect(result).toMatchObject({ result: { ok: true }, values: {} });
 	});
 
 	it("parses structured JSON fields before dispatching real brand and localization forms", async () => {