@marianmeres/stuic 3.157.0 → 3.158.0

package/dist/components/Checkout/CheckoutGuestForm.svelte

@@ -70,7 +70,12 @@
 </script>
 
 <script lang="ts">
+	import { untrack } from "svelte";
 	import { twMerge } from "../../utils/tw-merge.js";
+	import {
+		createExternalFieldErrors,
+		repaintFieldErrors,
+	} from "../../utils/field-errors.svelte.js";
 	import {
 		scrollToFirstInvalidField,
 		validateAllFields,
@@ -83,6 +88,7 @@
 	import Button from "../Button/Button.svelte";
 	import FieldInput from "../Input/FieldInput.svelte";
 	import FieldPhoneNumber from "../Input/FieldPhoneNumber.svelte";
+	import { validatePhoneNumber } from "../Input/phone-validation.js";
 
 	let {
 		formData = $bindable(createEmptyCustomerFormData()),
@@ -110,11 +116,58 @@
 	// Internal validation errors (set on submit)
 	let internalErrors = $state<CheckoutValidationError[]>([]);
 
+	/** Is this field currently rendered? (B2B block + per-field `fields` opt-outs) */
+	function _isRendered(field: string): boolean {
+		switch (field) {
+			case "email":
+				return true;
+			case "first_name":
+			case "last_name":
+			case "phone":
+				return fields?.[field] !== false;
+			case "company_name":
+			case "tax_id":
+			case "vat_number":
+				return showB2bFields && fields?.[field] !== false;
+			default:
+				return false;
+		}
+	}
+
+	// Clear internal field errors as soon as the user edits the form, so a previous
+	// failed submit's errors don't linger after the user has fixed them — matching
+	// the other STUIC forms. `untrack` the read+write so this effect re-runs only
+	// on formData changes, not when handleSubmit sets internalErrors.
+	$effect(() => {
+		void formData.email;
+		void formData.first_name;
+		void formData.last_name;
+		void formData.phone;
+		void formData.company_name;
+		void formData.tax_id;
+		void formData.vat_number;
+		untrack(() => {
+			if (internalErrors.length) internalErrors = [];
+		});
+	});
+
+	// Give the consumer-owned `errors` prop a lifecycle: an entry for a field this
+	// form renders self-clears once the user edits it, instead of blocking submit
+	// forever through the gate below (the consumer's own handler, which would have
+	// cleared the errors, is exactly what was being suppressed). Entries for
+	// anything else keep blocking until the consumer drops them.
+	const external = createExternalFieldErrors({
+		errors: () => externalErrors,
+		isRendered: _isRendered,
+		valueOf: (field) =>
+			(formData as unknown as Record<string, string | undefined>)[field] ?? "",
+	});
+
 	// Merge internal + external errors; external takes precedence per field
 	let allErrors = $derived.by(() => {
 		const map = new Map<string, string>();
 		for (const e of internalErrors) map.set(e.field, e.message);
-		for (const e of externalErrors) map.set(e.field, e.message);
+		for (const e of external.live) map.set(e.field, e.message);
 		return [...map.entries()].map(([field, message]) => ({ field, message }));
 	});
 
@@ -132,7 +185,8 @@
 
 		internalErrors = validationErrors;
 
-		if (validationErrors.length === 0 && externalErrors.length === 0) {
+		if (validationErrors.length === 0 && external.live.length === 0) {
+			external.markSubmitted();
 			onSubmit(formData);
 		}
 	}
@@ -167,11 +221,41 @@
 		];
 	}
 
+	function _fieldByName(name: string) {
+		if (!_isRendered(name)) return undefined;
+		switch (name) {
+			case "email":
+				return emailField;
+			case "first_name":
+				return firstNameField;
+			case "last_name":
+				return lastNameField;
+			case "phone":
+				return phoneField;
+			case "company_name":
+				return companyNameField;
+			case "tax_id":
+				return taxIdField;
+			case "vat_number":
+				return vatNumberField;
+			default:
+				return undefined;
+		}
+	}
+
+	// Paint newly-arrived error messages without waiting for the user's next
+	// interaction — otherwise a failed validation (or a server `errors` delivery)
+	// blocked the submit with no message anywhere.
+	repaintFieldErrors(() => allErrors, _fieldByName);
+
 	/**
 	 * Run every visible field's validator and render any inline errors.
 	 * Returns true if all fields are valid.
 	 */
 	export function validate(): boolean {
+		// Consumers posting from their own handler never reach `handleSubmit`, so
+		// this has to arm the same "a round-trip is starting" flag.
+		external.markSubmitted();
 		return validateAllFields(_fields());
 	}
 
@@ -201,9 +285,11 @@
 	{...rest}
 >
 	<!--
-		svelte-ignore binding_property_non_reactive:
-		formData is a $bindable prop — deep reactivity depends on the consumer
-		passing a $state() object. The bindings work correctly regardless.
+		NOTE on `binding_property_non_reactive`: formData is a $bindable prop — deep
+		reactivity depends on the consumer passing a $state() object. The bindings
+		work correctly regardless; the per-field directives below silence the hint.
+		(This block intentionally does NOT start with the literal directive word so
+		it isn't parsed as one — every following word would become a bogus code.)
 	-->
 	<!-- Email (always shown, always required) -->
 	<!-- svelte-ignore binding_property_non_reactive -->
@@ -235,6 +321,11 @@
 					labelLeftBreakpoint={0}
 					placeholder={t("checkout.guest.first_name_placeholder")}
 					name="checkout-guest-first-name"
+					validate={{
+						customValidator() {
+							return fieldError("first_name") || "";
+						},
+					}}
 				/>
 			{/if}
 			{#if fields?.last_name !== false}
@@ -246,6 +337,11 @@
 					labelLeftBreakpoint={0}
 					placeholder={t("checkout.guest.last_name_placeholder")}
 					name="checkout-guest-last-name"
+					validate={{
+						customValidator() {
+							return fieldError("last_name") || "";
+						},
+					}}
 				/>
 			{/if}
 		</div>
@@ -261,6 +357,14 @@
 			placeholder={t("checkout.guest.phone_placeholder")}
 			name="checkout-guest-phone"
 			labelLeftBreakpoint={0}
+			validate={{
+				// FieldPhoneNumber's customValidator REPLACES its built-in
+				// `validatePhoneNumber`, so surface the server error and then
+				// delegate rather than knocking phone validation out.
+				customValidator(val, ctx, el) {
+					return fieldError("phone") || validatePhoneNumber(val, ctx, el) || "";
+				},
+			}}
 			{...phoneFieldProps}
 		/>
 	{/if}
@@ -280,6 +384,11 @@
 						label={t("checkout.guest.company_name_label")}
 						name="checkout-guest-company-name"
 						labelLeftBreakpoint={0}
+						validate={{
+							customValidator() {
+								return fieldError("company_name") || "";
+							},
+						}}
 					/>
 				{/if}
 				{#if fields?.tax_id !== false || fields?.vat_number !== false}
@@ -291,6 +400,11 @@
 								bind:value={formData.tax_id}
 								label={t("checkout.guest.tax_id_label")}
 								name="checkout-guest-tax-id"
+								validate={{
+									customValidator() {
+										return fieldError("tax_id") || "";
+									},
+								}}
 							/>
 						{/if}
 						{#if fields?.vat_number !== false}
@@ -300,6 +414,11 @@
 								bind:value={formData.vat_number}
 								label={t("checkout.guest.vat_number_label")}
 								name="checkout-guest-vat-number"
+								validate={{
+									customValidator() {
+										return fieldError("vat_number") || "";
+									},
+								}}
 							/>
 						{/if}
 					</div>

package/dist/components/Checkout/CheckoutGuestOrLoginForm.svelte

@@ -78,8 +78,10 @@
 			| "registerProps"
 			| "verifyProps"
 			| "socialLogins"
+			| "socialPosition"
 			| "socialDividerLabel"
 			| "footer"
+			| "animateHeight"
 			| "modeSwitcher"
 			| "loginModeLabel"
 			| "registerModeLabel"
@@ -445,7 +447,9 @@
 			registerModeLabel={loginOrRegisterModal.registerModeLabel}
 			verifyModeLabel={loginOrRegisterModal.verifyModeLabel}
 			socialLogins={loginOrRegisterModal.socialLogins}
+			socialPosition={loginOrRegisterModal.socialPosition}
 			socialDividerLabel={loginOrRegisterModal.socialDividerLabel}
+			animateHeight={loginOrRegisterModal.animateHeight}
 			footer={loginOrRegisterModal.footer}
 			{notifications}
 			title={loginOrRegisterModal.title}

package/dist/components/Checkout/CheckoutGuestOrLoginForm.svelte.d.ts

@@ -39,7 +39,7 @@ export interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "children">
      * flip into verify mode (e.g., on a `requiresVerification` server response),
      * the consumer updates its own `mode` state and the new value flows down.
      */
-    loginOrRegisterModal?: Pick<LoginOrRegisterFormModalProps, "title" | "classModal" | "classInner" | "classForm" | "noXClose" | "noClickOutsideClose" | "onClose" | "mode" | "verifyEmail" | "onLogin" | "onRegister" | "onVerify" | "onResendCode" | "onForgotPassword" | "onModeChange" | "isSubmitting" | "loginProps" | "registerProps" | "verifyProps" | "socialLogins" | "socialDividerLabel" | "footer" | "modeSwitcher" | "loginModeLabel" | "registerModeLabel" | "verifyModeLabel">;
+    loginOrRegisterModal?: Pick<LoginOrRegisterFormModalProps, "title" | "classModal" | "classInner" | "classForm" | "noXClose" | "noClickOutsideClose" | "onClose" | "mode" | "verifyEmail" | "onLogin" | "onRegister" | "onVerify" | "onResendCode" | "onForgotPassword" | "onModeChange" | "isSubmitting" | "loginProps" | "registerProps" | "verifyProps" | "socialLogins" | "socialPosition" | "socialDividerLabel" | "footer" | "animateHeight" | "modeSwitcher" | "loginModeLabel" | "registerModeLabel" | "verifyModeLabel">;
     /** Tab label for the guest form tab. Default from i18n. */
     guestTabLabel?: string;
     /** Tab label for the login form tab. Default from i18n. */

package/dist/components/ContactUsForm/ContactUsForm.svelte

@@ -132,6 +132,10 @@
 		scrollToFirstInvalidField,
 		validateAllFields,
 	} from "../../utils/validate-fields.js";
+	import {
+		createExternalFieldErrors,
+		repaintFieldErrors,
+	} from "../../utils/field-errors.svelte.js";
 
 	let {
 		formData = $bindable(createEmptyContactFormData()),
@@ -217,11 +221,70 @@
 		});
 	});
 
+	// Seed `ContactFieldConfig.initialValue` into `formData.extra`. `extraValue()`
+	// only ever used it as a *display* fallback, so an untouched field with a
+	// required `initialValue` failed validation ("… is required") while its value
+	// sat plainly visible in the input, and an untouched optional one submitted
+	// `undefined`. Never clobbers a value the consumer already provided. `.pre` so
+	// the seed lands before first paint; the bare `formData.extra` read tracks a
+	// wholesale replacement of the container without tracking the per-key writes.
+	$effect.pre(() => {
+		const seeds = extraFields
+			.filter((f) => f.initialValue != null)
+			.map((f) => [f.name, f.initialValue] as const);
+		void formData.extra;
+		if (!seeds.length) return;
+		untrack(() => {
+			if (!formData.extra) formData.extra = {};
+			for (const [name, initialValue] of seeds) {
+				if (formData.extra[name] == null) formData.extra[name] = initialValue;
+			}
+		});
+	});
+
+	// Give the consumer-owned `errors` prop a lifecycle: an entry for a field this
+	// form renders self-clears once the user edits it, instead of wedging the form
+	// forever (the field's customValidator kept reporting it, so every later
+	// submit was routed to `submit_invalid` — including the consumer's own handler
+	// that would have cleared the errors). Entries for anything else keep blocking
+	// until the consumer drops them. See `createExternalFieldErrors`.
+	const external = createExternalFieldErrors({
+		errors: () => externalErrors,
+		isRendered(field) {
+			if (field === "name") return showName;
+			if (field === "phone") return showPhone;
+			if (field === "subject") return subjectShown;
+			if (field === "company") return showCompany;
+			if (field === "email" || field === "message") return true;
+			return extraFields.some((f) => f.name === field);
+		},
+		valueOf(field) {
+			switch (field) {
+				case "name":
+					return formData.name ?? "";
+				case "email":
+					return formData.email ?? "";
+				case "phone":
+					return formData.phone ?? "";
+				case "subject":
+					return formData.subject ?? "";
+				case "company":
+					return formData.company ?? "";
+				case "message":
+					return formData.message ?? "";
+				default: {
+					const v = formData.extra?.[field];
+					return v == null ? "" : String(v);
+				}
+			}
+		},
+	});
+
 	// Merge internal + external errors; external takes precedence per field.
 	let allErrors = $derived.by(() => {
 		const map = new Map<string, string>();
 		for (const e of internalErrors) map.set(e.field, e.message);
-		for (const e of externalErrors) map.set(e.field, e.message);
+		for (const e of external.live) map.set(e.field, e.message);
 		return [...map.entries()].map(([field, message]) => ({ field, message }));
 	});
 
@@ -274,7 +337,8 @@
 
 		// Report-only on bot signals: we still submit when field validation passes
 		// and hand the consumer the botCheck to enforce server-side.
-		if (validationErrors.length === 0 && externalErrors.length === 0) {
+		if (validationErrors.length === 0 && external.live.length === 0) {
+			external.markSubmitted();
 			onSubmit(formData, buildBotCheck());
 		}
 	}
@@ -298,8 +362,10 @@
 	);
 
 	// Imperative API ----------------------------------------------------------
-	let topFieldRefs: (FieldInput | undefined)[] = $state([]);
-	let bottomFieldRefs: (FieldInput | undefined)[] = $state([]);
+	// Extra-field refs are keyed by `cfg.name`, NOT by `{#each}` index: the each
+	// block is keyed by name, so an index-based array pointed at the wrong
+	// component after any reorder of `extraFields`.
+	let extraFieldRefs = $state<Record<string, FieldInput | undefined>>({});
 	let nameField = $state<FieldInput>();
 	let emailField = $state<FieldInput>();
 	let phoneField = $state<FieldInput>();
@@ -309,22 +375,53 @@
 
 	function _fields() {
 		return [
-			...topFieldRefs,
+			...topFields.map((f) => extraFieldRefs[f.name]),
 			...(showName ? [nameField] : []),
 			emailField,
 			...(showPhone ? [phoneField] : []),
 			...(showCompany ? [companyField] : []),
 			...(subjectShown ? [subjectField] : []),
 			messageField,
-			...bottomFieldRefs,
+			...bottomFields.map((f) => extraFieldRefs[f.name]),
 		];
 	}
 
+	function _fieldByName(name: string) {
+		switch (name) {
+			case "name":
+				return showName ? nameField : undefined;
+			case "email":
+				return emailField;
+			case "phone":
+				return showPhone ? phoneField : undefined;
+			case "company":
+				return showCompany ? companyField : undefined;
+			case "subject":
+				return subjectShown ? subjectField : undefined;
+			case "message":
+				return messageField;
+			default:
+				return extraFields.some((f) => f.name === name)
+					? extraFieldRefs[name]
+					: undefined;
+		}
+	}
+
+	// Paint newly-arrived error messages without waiting for the user's next
+	// interaction. `validateContactForm` runs on `submit_valid` — after the
+	// validity walk has already re-run every field's validator — and a server
+	// `errors` delivery lands once the submit is over, so without this the first
+	// failed click was a button that did nothing, with no message anywhere.
+	repaintFieldErrors(() => allErrors, _fieldByName);
+
 	/**
 	 * Run every visible field's validator and render any inline errors. Returns
 	 * true if all fields are valid. Useful from custom submit handlers.
 	 */
 	export function validate(): boolean {
+		// Consumers posting from their own handler never reach `handleSubmitValid`,
+		// so this has to arm the same "a round-trip is starting" flag.
+		external.markSubmitted();
 		return validateAllFields(_fields());
 	}
 
@@ -344,9 +441,9 @@
 	<DismissibleMessage message={error} intent="destructive" />
 
 	<!-- Top-position extra fields -->
-	{#each topFields as cfg, i (cfg.name)}
+	{#each topFields as cfg (cfg.name)}
 		<FieldInput
-			bind:this={topFieldRefs[i]}
+			bind:this={extraFieldRefs[cfg.name]}
 			value={extraValue(cfg)}
 			oninput={(e: Event) =>
 				setExtraValue(cfg, (e.currentTarget as HTMLInputElement).value)}
@@ -511,9 +608,9 @@
 	/>
 
 	<!-- Bottom-position extra fields (default) -->
-	{#each bottomFields as cfg, i (cfg.name)}
+	{#each bottomFields as cfg (cfg.name)}
 		<FieldInput
-			bind:this={bottomFieldRefs[i]}
+			bind:this={extraFieldRefs[cfg.name]}
 			value={extraValue(cfg)}
 			oninput={(e: Event) =>
 				setExtraValue(cfg, (e.currentTarget as HTMLInputElement).value)}

package/dist/components/ContactUsForm/README.md

@@ -63,7 +63,7 @@ interface ContactFieldConfig {
 | `formData`           | `ContactFormData`                                            | empty    | Bindable form data.                                                                                                 |
 | `onSubmit`           | `(data: ContactFormData, botCheck: ContactBotCheck) => void` | required | Called after client-side validation passes. `botCheck` is report-only.                                              |
 | `isSubmitting`       | `boolean`                                                    | `false`  | Disables the CTA during submission.                                                                                 |
-| `errors`             | `ContactFormValidationError[]`                               | `[]`     | Field-specific server errors (merged with internal validation).                                                     |
+| `errors`             | `ContactFormValidationError[]`                               | `[]`     | Field-specific server errors (merged with internal validation); self-clearing (see below).                          |
 | `error`              | `string`                                                     | -        | General error rendered as a `DismissibleMessage` above the form.                                                    |
 | `showName`           | `boolean`                                                    | `false`  | Render the Name field.                                                                                              |
 | `requireName`        | `boolean`                                                    | `true`   | Require Name (only applies when shown).                                                                             |
@@ -193,6 +193,21 @@ automatically; the bound value is still the chosen string in `formData.subject`)
 />
 ```
 
+## Server-supplied errors
+
+`errors` is consumer-owned — the form renders it but cannot clear it. An entry for a field **this form renders** is therefore tied to the value that field held when the error arrived, and goes **stale** as soon as the user edits it: it stops blocking submit and disappears from the inline messages on that field's next validation run. Typing the rejected value back in makes it live again.
+
+The rule in one line: **errors the user can fix here clear themselves; everything else is yours to clear.** Without the first half the form used to wedge permanently after any server-side field error — the consumer's own "clear errors on submit" code cannot help, because their submit handler is exactly what was being suppressed.
+
+Notes:
+
+- An error whose `field` isn't rendered here keeps blocking until you drop it from `errors`. Nothing in the form can answer it, and auto-clearing it would let the form post past a block you set deliberately.
+- Messages are painted as soon as they arrive; no extra click is needed.
+- Staleness is keyed on the errors' _content_, not the array identity, so passing a freshly built array on every render is safe. An identical error redelivered after a resubmit is treated as fresh.
+- If you post from your own handler instead of `onSubmit`, call `validate()` first — that is what marks the round trip.
+
+Shared with the other STUIC forms via `createExternalFieldErrors` (see the [utils domain](../../../docs/domains/utils.md)).
+
 ## CSS Variables
 
 Prefix: `--stuic-contact-us-form-*`

package/dist/components/ContactUsForm/_internal/contact-form-types.d.ts

@@ -45,7 +45,12 @@ export interface ContactFieldConfig {
     placeholder?: string;
     required?: boolean;
     autocomplete?: HTMLInputAttributes["autocomplete"];
-    /** Initial value to seed into `formData.extra[name]` if undefined. */
+    /**
+     * Initial value seeded into `formData.extra[name]` when that key is null-ish.
+     * Seeded raw (your type is preserved), while user edits always write strings —
+     * so prefer a string here, otherwise a numeric seed reaches `validate` /
+     * `onSubmit` as a number before the first edit and as a string after it.
+     */
     initialValue?: unknown;
     /**
      * Synchronous validator. Return empty string / undefined for "valid".

package/dist/components/LoginForm/LoginForm.svelte

@@ -85,6 +85,10 @@
 		scrollToFirstInvalidField,
 		validateAllFields,
 	} from "../../utils/validate-fields.js";
+	import {
+		createExternalFieldErrors,
+		repaintFieldErrors,
+	} from "../../utils/field-errors.svelte.js";
 	import Button from "../Button/Button.svelte";
 	import DismissibleMessage from "../DismissibleMessage/DismissibleMessage.svelte";
 	import FieldCheckbox from "../Input/FieldCheckbox.svelte";
@@ -135,11 +139,23 @@
 	// Internal validation errors (set on submit)
 	let internalErrors = $state<LoginFormValidationError[]>([]);
 
+	// Give the consumer-owned `errors` prop a lifecycle: an entry for a field this
+	// form renders self-clears once the user edits it, instead of wedging the form
+	// forever (the field's customValidator kept reporting it, so every later
+	// submit was routed to `submit_invalid` — including the consumer's own handler
+	// that would have cleared the errors). Entries for anything else keep blocking
+	// until the consumer drops them. See `createExternalFieldErrors`.
+	const external = createExternalFieldErrors({
+		errors: () => externalErrors,
+		isRendered: (field) => field === "email" || field === "password",
+		valueOf: (field) => (field === "email" ? formData.email : formData.password) ?? "",
+	});
+
 	// Merge internal + external errors; external takes precedence per field
 	let allErrors = $derived.by(() => {
 		const map = new Map<string, string>();
 		for (const e of internalErrors) map.set(e.field, e.message);
-		for (const e of externalErrors) map.set(e.field, e.message);
+		for (const e of external.live) map.set(e.field, e.message);
 		return [...map.entries()].map(([field, message]) => ({ field, message }));
 	});
 
@@ -180,7 +196,8 @@
 		// 		validationErrors.length === 0 && externalErrors.length === 0,
 		// });
 
-		if (validationErrors.length === 0 && externalErrors.length === 0) {
+		if (validationErrors.length === 0 && external.live.length === 0) {
+			external.markSubmitted();
 			onSubmit(formData);
 		}
 	}
@@ -228,11 +245,27 @@
 		return [emailField, passwordField];
 	}
 
+	function _fieldByName(name: string): FieldInput | undefined {
+		if (name === "email") return emailField;
+		if (name === "password") return passwordField;
+		return undefined;
+	}
+
+	// Paint newly-arrived error messages without waiting for the user's next
+	// interaction. `validateLoginForm` runs on `submit_valid` — after the validity
+	// walk has already re-run every field's validator — and a server `errors`
+	// delivery lands once the submit is over, so without this the first failed
+	// click was a button that did nothing, with no message anywhere.
+	repaintFieldErrors(() => allErrors, _fieldByName);
+
 	/**
 	 * Run every field's validator and render any inline errors. Returns true
 	 * if all fields are valid. Useful from custom submit handlers.
 	 */
 	export function validate(): boolean {
+		// Consumers posting from their own handler never reach `handleSubmitValid`,
+		// so this has to arm the same "a round-trip is starting" flag.
+		external.markSubmitted();
 		return validateAllFields(_fields());
 	}
 
@@ -252,9 +285,11 @@
 	<DismissibleMessage message={error} intent="destructive" />
 
 	<!--
-		svelte-ignore binding_property_non_reactive:
-		formData is a $bindable prop — deep reactivity depends on the consumer
-		passing a $state() object. The bindings work correctly regardless.
+		NOTE on `binding_property_non_reactive`: formData is a $bindable prop — deep
+		reactivity depends on the consumer passing a $state() object. The bindings
+		work correctly regardless; the per-field directives below silence the hint.
+		(This block intentionally does NOT start with the literal directive word so
+		it isn't parsed as one — every following word would become a bogus code.)
 	-->
 	<!-- Email -->
 	<!-- svelte-ignore binding_property_non_reactive -->

package/dist/components/LoginForm/README.md

@@ -19,25 +19,25 @@ Standalone login form with email/password fields, optional social/OAuth buttons,
 
 ## LoginForm — Props
 
-| Prop                 | Type                                    | Default  | Description                                                                      |
-| -------------------- | --------------------------------------- | -------- | -------------------------------------------------------------------------------- |
-| `formData`           | `LoginFormData`                         | empty    | Bindable form data.                                                              |
-| `onSubmit`           | `(data: LoginFormData) => void`         | required | Called when client-side validation passes.                                       |
-| `isSubmitting`       | `boolean`                               | `false`  | Disables the CTA during submission.                                              |
-| `errors`             | `LoginFormValidationError[]`            | `[]`     | Field-specific server errors (merged with internal validation).                  |
-| `error`              | `string`                                | -        | General error rendered as a `DismissibleMessage` above the form.                 |
-| `onForgotPassword`   | `() => void`                            | -        | Click handler for the "Forgot password?" link. Link is hidden when undefined.    |
-| `showRememberMe`     | `boolean`                               | `true`   | Render the remember-me checkbox.                                                 |
-| `submitLabel`        | `string`                                | i18n     | Override the CTA label.                                                          |
-| `submittingLabel`    | `string`                                | i18n     | Override the CTA label while submitting.                                         |
-| `submitButton`       | `Snippet<[{ isSubmitting, disabled }]>` | -        | Override the entire CTA section.                                                 |
-| `socialLogins`       | `Snippet`                               | -        | Social/OAuth buttons rendered below the form. A divider is shown above when set. |
-| `socialDividerLabel` | `string \| false`                       | i18n     | Override (or hide with `false`) the divider above social buttons.                |
-| `footer`             | `Snippet`                               | -        | Content below the form (e.g., sign-up links).                                    |
-| `notifications`      | `NotificationsStack`                    | -        | When set, general errors are also pushed via `notifications.error()`.            |
-| `t`                  | `TranslateFn`                           | English  | i18n function.                                                                   |
-| `unstyled` / `class` | -                                       | -        | Standard styling escape hatches.                                                 |
-| `el`                 | `HTMLFormElement`                       | -        | Bindable form element.                                                           |
+| Prop                 | Type                                    | Default  | Description                                                                                |
+| -------------------- | --------------------------------------- | -------- | ------------------------------------------------------------------------------------------ |
+| `formData`           | `LoginFormData`                         | empty    | Bindable form data.                                                                        |
+| `onSubmit`           | `(data: LoginFormData) => void`         | required | Called when client-side validation passes.                                                 |
+| `isSubmitting`       | `boolean`                               | `false`  | Disables the CTA during submission.                                                        |
+| `errors`             | `LoginFormValidationError[]`            | `[]`     | Field-specific server errors (merged with internal validation); self-clearing (see below). |
+| `error`              | `string`                                | -        | General error rendered as a `DismissibleMessage` above the form.                           |
+| `onForgotPassword`   | `() => void`                            | -        | Click handler for the "Forgot password?" link. Link is hidden when undefined.              |
+| `showRememberMe`     | `boolean`                               | `true`   | Render the remember-me checkbox.                                                           |
+| `submitLabel`        | `string`                                | i18n     | Override the CTA label.                                                                    |
+| `submittingLabel`    | `string`                                | i18n     | Override the CTA label while submitting.                                                   |
+| `submitButton`       | `Snippet<[{ isSubmitting, disabled }]>` | -        | Override the entire CTA section.                                                           |
+| `socialLogins`       | `Snippet`                               | -        | Social/OAuth buttons rendered below the form. A divider is shown above when set.           |
+| `socialDividerLabel` | `string \| false`                       | i18n     | Override (or hide with `false`) the divider above social buttons.                          |
+| `footer`             | `Snippet`                               | -        | Content below the form (e.g., sign-up links).                                              |
+| `notifications`      | `NotificationsStack`                    | -        | When set, general errors are also pushed via `notifications.error()`.                      |
+| `t`                  | `TranslateFn`                           | English  | i18n function.                                                                             |
+| `unstyled` / `class` | -                                       | -        | Standard styling escape hatches.                                                           |
+| `el`                 | `HTMLFormElement`                       | -        | Bindable form element.                                                                     |
 
 ### Imperative methods
 
@@ -127,6 +127,21 @@ Inherits all `LoginForm` props, plus:
 <Button onclick={submit}>Submit from outside</Button>
 ```
 
+## Server-supplied errors
+
+`errors` is consumer-owned — the form renders it but cannot clear it. An entry for a field **this form renders** is therefore tied to the value that field held when the error arrived, and goes **stale** as soon as the user edits it: it stops blocking submit and disappears from the inline messages on that field's next validation run. Typing the rejected value back in makes it live again.
+
+The rule in one line: **errors the user can fix here clear themselves; everything else is yours to clear.** Without the first half the form used to wedge permanently after any server-side field error — the consumer's own "clear errors on submit" code cannot help, because their submit handler is exactly what was being suppressed.
+
+Notes:
+
+- An error whose `field` isn't rendered here keeps blocking until you drop it from `errors`. Nothing in the form can answer it, and auto-clearing it would let the form post past a block you set deliberately.
+- Messages are painted as soon as they arrive; no extra click is needed.
+- Staleness is keyed on the errors' _content_, not the array identity, so passing a freshly built array on every render is safe. An identical error redelivered after a resubmit is treated as fresh.
+- If you post from your own handler instead of `onSubmit`, call `validate()` first — that is what marks the round trip.
+
+Shared with the other STUIC forms via `createExternalFieldErrors` (see the [utils domain](../../../docs/domains/utils.md)).
+
 ## CSS Variables
 
 Prefix: `--stuic-login-form-*`