@marianmeres/stuic 3.157.0 → 3.158.0

package/dist/components/RegisterForm/RegisterForm.svelte.d.ts

@@ -1,6 +1,7 @@
 import type { Snippet } from "svelte";
 import type { HTMLAttributes } from "svelte/elements";
 import type { TranslateFn } from "../../types.js";
+import type { Props as FieldInputProps } from "../Input/FieldInput.svelte";
 import type { RegisterFieldConfig, RegisterFormData, RegisterFormValidationError } from "./_internal/register-form-types.js";
 import type { NotificationsStack } from "../Notifications/notifications-stack.svelte.js";
 export interface Props extends Omit<HTMLAttributes<HTMLFormElement>, "children"> {
@@ -10,6 +11,17 @@ export interface Props extends Omit<HTMLAttributes<HTMLFormElement>, "children">
     onSubmit: (data: RegisterFormData) => void;
     /** Whether the form is currently submitting (disables CTA) */
     isSubmitting?: boolean;
+    /**
+     * Consumer-owned reason to refuse submission which is neither "submitting"
+     * nor a field error — e.g. an external identity whose server-side TTL has
+     * lapsed, an unchecked terms box rendered in `extraFieldsSlot`, or an async
+     * availability check still in flight.
+     *
+     * Disables the default CTA, is reflected in the `submitButton` snippet
+     * payload, and also prevents `onSubmit` from firing at all — so a custom
+     * `submitButton` which ignores `disabled` still cannot post. Default: false
+     */
+    submitDisabled?: boolean;
     /** Field-specific validation errors (e.g., from server) */
     errors?: RegisterFormValidationError[];
     /**
@@ -18,10 +30,57 @@ export interface Props extends Omit<HTMLAttributes<HTMLFormElement>, "children">
      * Example: "Email already registered"
      */
     error?: string;
-    /** Show password confirmation field. Default: true */
+    /**
+     * Render the built-in email field. When false the field is UNMOUNTED (not
+     * hidden) and skipped by validation — use it when the account identity is
+     * established elsewhere (OAuth provider, invite token, magic link) and pair
+     * it with `credentialsSlot`. Default: true
+     */
+    showEmail?: boolean;
+    /**
+     * Render the built-in password field. When false it (and, transitively, the
+     * confirm field) is UNMOUNTED and skipped by validation — e.g. passwordless
+     * / identity-first signup. Default: true
+     */
+    showPassword?: boolean;
+    /**
+     * Show password confirmation field. Subordinate to `showPassword`:
+     * `showPassword={false}` implies no confirm field regardless. Default: true
+     */
     showPasswordConfirm?: boolean;
     /** Minimum password length. Fed into FieldInput `minlength` + validator. Default: 8 */
     passwordMinLength?: number;
+    /**
+     * Rendered at the credentials position — after whatever core fields are
+     * still shown, before the bottom-position extra fields.
+     *
+     * Combined with `showEmail` / `showPassword` = false this REPLACES the
+     * credential block: use it for an identity established elsewhere ("Signed
+     * in as x@y.z — change / use a password instead"), an invite summary, or a
+     * magic-link explainer. Receives `formData` and a `fieldError(name)` lookup.
+     */
+    credentialsSlot?: Snippet<[
+        {
+            formData: RegisterFormData;
+            fieldError: (name: string) => string | undefined;
+        }
+    ]>;
+    /**
+     * Passthrough props merged onto the built-in email `FieldInput`, applied
+     * AFTER the component's own — so `label`, `placeholder`, `description`,
+     * `autocomplete`, `renderSize`, `classInput`… are overridable without
+     * supplying a full `t`.
+     *
+     * `validate` is composed rather than replaced: your `customValidator` runs
+     * when there is no server/internal error for the field, so the `errors`
+     * wiring can't be knocked out by accident (`validate: false` is ignored for
+     * the same reason). `value` is ignored — the field is bound to `formData`.
+     */
+    emailFieldProps?: Partial<FieldInputProps>;
+    /** Passthrough props for the built-in password field. See `emailFieldProps`. */
+    passwordFieldProps?: Partial<FieldInputProps>;
+    /** Passthrough props for the built-in confirm field. See `emailFieldProps`. */
+    passwordConfirmFieldProps?: Partial<FieldInputProps>;
     /**
      * Declarative extra fields rendered as FieldInput entries.
      * Values bind into `formData.extra[name]`.
@@ -54,8 +113,22 @@ export interface Props extends Omit<HTMLAttributes<HTMLFormElement>, "children">
      */
     socialLogins?: Snippet;
     /**
-     * Override the divider label above social login buttons.
-     * Default: i18n key "register_form.social_divider" ("or continue with").
+     * Where the social block sits relative to the credentials:
+     * - `"bottom"` (default) — after the CTA, divider ABOVE the buttons
+     * - `"top"` — between the top-position extra fields and the credentials,
+     *   divider BELOW the buttons
+     *
+     * `"top"` suits identity-first signup, where the provider button is an
+     * alternative to the credentials only — fields required on both paths
+     * (workspace id, invite code…) stay above the choice. Default: "bottom"
+     */
+    socialPosition?: "top" | "bottom";
+    /**
+     * Override the divider label next to the social login buttons.
+     * Default: i18n key "register_form.social_divider" ("or continue with") at
+     * the bottom position, "register_form.social_divider_alt" ("or") at the top
+     * one — where the divider faces the credentials, so "or continue with"
+     * would read backwards.
      * Set to `false` to hide the divider while still rendering socialLogins.
      */
     socialDividerLabel?: string | false;
@@ -75,6 +148,7 @@ import { scrollToFirstInvalidField } from "../../utils/validate-fields.js";
 declare const RegisterForm: import("svelte").Component<Props, {
     validate: () => boolean;
     scrollToFirstError: (opts?: Parameters<typeof scrollToFirstInvalidField>[1]) => boolean;
+    focusField: (name: string) => boolean;
 }, "el" | "formData">;
 type RegisterForm = ReturnType<typeof RegisterForm>;
 export default RegisterForm;

package/dist/components/RegisterForm/RegisterFormModal.svelte

@@ -7,6 +7,7 @@
 		RegisterFormValidationError,
 	} from "./_internal/register-form-types.js";
 	import type { NotificationsStack } from "../Notifications/notifications-stack.svelte.js";
+	import type { Props as InnerProps } from "./RegisterForm.svelte";
 
 	export interface Props {
 		/** Bindable register data. Default: createEmptyRegisterFormData() */
@@ -18,6 +19,12 @@
 		/** Whether the form is currently submitting (disables CTA) */
 		isSubmitting?: boolean;
 
+		/**
+		 * Consumer-owned reason to refuse submission (stale token, unchecked terms,
+		 * async check in flight…). Also blocks `onSubmit`. Default: false
+		 */
+		submitDisabled?: boolean;
+
 		/** Field-specific validation errors (e.g., from server) */
 		errors?: RegisterFormValidationError[];
 
@@ -27,12 +34,34 @@
 		 */
 		error?: string;
 
+		/** Render the built-in email field (unmounted when false). Default: true */
+		showEmail?: boolean;
+
+		/** Render the built-in password field (unmounted when false). Default: true */
+		showPassword?: boolean;
+
 		/** Show password confirmation field. Default: true */
 		showPasswordConfirm?: boolean;
 
 		/** Minimum password length. Default: 8 */
 		passwordMinLength?: number;
 
+		/**
+		 * Rendered at the credentials position. Combined with `showEmail` /
+		 * `showPassword` = false it replaces the credential block (identity-first
+		 * signup, invite summary, magic-link explainer).
+		 */
+		credentialsSlot?: InnerProps["credentialsSlot"];
+
+		/** Passthrough props for the built-in email field. */
+		emailFieldProps?: InnerProps["emailFieldProps"];
+
+		/** Passthrough props for the built-in password field. */
+		passwordFieldProps?: InnerProps["passwordFieldProps"];
+
+		/** Passthrough props for the built-in confirm field. */
+		passwordConfirmFieldProps?: InnerProps["passwordConfirmFieldProps"];
+
 		/** Declarative extra fields */
 		extraFields?: RegisterFieldConfig[];
 
@@ -60,6 +89,12 @@
 		 */
 		socialLogins?: Snippet;
 
+		/**
+		 * Where the social block sits relative to the credentials.
+		 * `"top"` renders it above them (divider below the buttons). Default: "bottom"
+		 */
+		socialPosition?: "top" | "bottom";
+
 		/**
 		 * Override the divider label above social login buttons.
 		 */
@@ -110,21 +145,30 @@
 	import { createEmptyRegisterFormData } from "./_internal/register-form-utils.js";
 	import { twMerge } from "../../utils/tw-merge.js";
 	import H from "../H/H.svelte";
+	import type { scrollToFirstInvalidField } from "../../utils/validate-fields.js";
 
 	let {
 		formData = $bindable(createEmptyRegisterFormData()),
 		onSubmit,
 		isSubmitting = false,
+		submitDisabled,
 		errors,
 		error,
+		showEmail,
+		showPassword,
 		showPasswordConfirm,
 		passwordMinLength,
+		credentialsSlot,
+		emailFieldProps,
+		passwordFieldProps,
+		passwordConfirmFieldProps,
 		extraFields,
 		extraFieldsSlot,
 		submitLabel,
 		submittingLabel,
 		submitButton,
 		socialLogins,
+		socialPosition,
 		socialDividerLabel,
 		footer,
 		notifications,
@@ -143,6 +187,7 @@
 	let t = $derived(tProp ?? t_default);
 
 	let modal: Modal = $state()!;
+	let form = $state<RegisterForm>();
 
 	export function open(openerOrEvent?: null | HTMLElement | MouseEvent) {
 		modal.open(openerOrEvent);
@@ -151,6 +196,30 @@
 	export function close() {
 		modal.close();
 	}
+
+	// Same imperative API the inner form exposes, forwarded. The form only exists
+	// while the modal is open, so all three are no-ops when it is closed.
+
+	/**
+	 * Run every field's validator. Returns true if all valid — including when the
+	 * modal is closed and there is no form to ask, so check `visible` first if
+	 * that distinction matters.
+	 */
+	export function validate(): boolean {
+		return form?.validate() ?? true;
+	}
+
+	/** Scroll + focus the first invalid field. Call after `validate()`. */
+	export function scrollToFirstError(
+		opts?: Parameters<typeof scrollToFirstInvalidField>[1]
+	): boolean {
+		return form?.scrollToFirstError(opts) ?? false;
+	}
+
+	/** Focus a field by name. Returns false if it is not currently rendered. */
+	export function focusField(name: string): boolean {
+		return form?.focusField(name) ?? false;
+	}
 </script>
 
 {#if trigger}
@@ -187,19 +256,28 @@
 
 	<div class="p-6 pt-3">
 		<RegisterForm
+			bind:this={form}
 			bind:formData
 			{onSubmit}
 			{isSubmitting}
+			{submitDisabled}
 			{errors}
 			{error}
+			{showEmail}
+			{showPassword}
 			{showPasswordConfirm}
 			{passwordMinLength}
+			{credentialsSlot}
+			{emailFieldProps}
+			{passwordFieldProps}
+			{passwordConfirmFieldProps}
 			{extraFields}
 			{extraFieldsSlot}
 			{submitLabel}
 			{submittingLabel}
 			{submitButton}
 			{socialLogins}
+			{socialPosition}
 			{socialDividerLabel}
 			{footer}
 			{notifications}

package/dist/components/RegisterForm/RegisterFormModal.svelte.d.ts

@@ -2,6 +2,7 @@ import type { Snippet } from "svelte";
 import type { TranslateFn } from "../../types.js";
 import type { RegisterFieldConfig, RegisterFormData, RegisterFormValidationError } from "./_internal/register-form-types.js";
 import type { NotificationsStack } from "../Notifications/notifications-stack.svelte.js";
+import type { Props as InnerProps } from "./RegisterForm.svelte";
 export interface Props {
     /** Bindable register data. Default: createEmptyRegisterFormData() */
     formData?: RegisterFormData;
@@ -9,6 +10,11 @@ export interface Props {
     onSubmit: (data: RegisterFormData) => void;
     /** Whether the form is currently submitting (disables CTA) */
     isSubmitting?: boolean;
+    /**
+     * Consumer-owned reason to refuse submission (stale token, unchecked terms,
+     * async check in flight…). Also blocks `onSubmit`. Default: false
+     */
+    submitDisabled?: boolean;
     /** Field-specific validation errors (e.g., from server) */
     errors?: RegisterFormValidationError[];
     /**
@@ -16,10 +22,26 @@ export interface Props {
      * Rendered as an alert box above the form.
      */
     error?: string;
+    /** Render the built-in email field (unmounted when false). Default: true */
+    showEmail?: boolean;
+    /** Render the built-in password field (unmounted when false). Default: true */
+    showPassword?: boolean;
     /** Show password confirmation field. Default: true */
     showPasswordConfirm?: boolean;
     /** Minimum password length. Default: 8 */
     passwordMinLength?: number;
+    /**
+     * Rendered at the credentials position. Combined with `showEmail` /
+     * `showPassword` = false it replaces the credential block (identity-first
+     * signup, invite summary, magic-link explainer).
+     */
+    credentialsSlot?: InnerProps["credentialsSlot"];
+    /** Passthrough props for the built-in email field. */
+    emailFieldProps?: InnerProps["emailFieldProps"];
+    /** Passthrough props for the built-in password field. */
+    passwordFieldProps?: InnerProps["passwordFieldProps"];
+    /** Passthrough props for the built-in confirm field. */
+    passwordConfirmFieldProps?: InnerProps["passwordConfirmFieldProps"];
     /** Declarative extra fields */
     extraFields?: RegisterFieldConfig[];
     /** Escape-hatch slot for non-FieldInput extras */
@@ -42,6 +64,11 @@ export interface Props {
      * Social/OAuth login buttons rendered below the primary form.
      */
     socialLogins?: Snippet;
+    /**
+     * Where the social block sits relative to the credentials.
+     * `"top"` renders it above them (divider below the buttons). Default: "bottom"
+     */
+    socialPosition?: "top" | "bottom";
     /**
      * Override the divider label above social login buttons.
      */
@@ -74,9 +101,13 @@ export interface Props {
     noXClose?: boolean;
     onClose?: () => false | void;
 }
+import type { scrollToFirstInvalidField } from "../../utils/validate-fields.js";
 declare const RegisterFormModal: import("svelte").Component<Props, {
     open: (openerOrEvent?: null | HTMLElement | MouseEvent) => void;
     close: () => void;
+    validate: () => boolean;
+    scrollToFirstError: (opts?: Parameters<typeof scrollToFirstInvalidField>[1]) => boolean;
+    focusField: (name: string) => boolean;
 }, "visible" | "formData">;
 type RegisterFormModal = ReturnType<typeof RegisterFormModal>;
 export default RegisterFormModal;

package/dist/components/RegisterForm/_internal/register-form-i18n-defaults.js

@@ -17,6 +17,7 @@ const DEFAULTS = {
     "register_form.password_mismatch": "Passwords do not match",
     "register_form.field_required": "{label} is required",
     "register_form.social_divider": "or continue with",
+    "register_form.social_divider_alt": "or",
     "register_form.already_have_account": "Already have an account?",
     "register_form.modal_title": "Create account",
 };

package/dist/components/RegisterForm/_internal/register-form-types.d.ts

@@ -12,7 +12,11 @@ export interface RegisterFormValidationError {
 }
 /** Declarative descriptor for a consumer-defined FieldInput-style extra field. */
 export interface RegisterFieldConfig {
-    /** Key under formData.extra where the value lives. Must be unique. */
+    /**
+     * Key under formData.extra where the value lives. Must be unique.
+     * `"email"`, `"password"` and `"passwordConfirm"` are reserved by the core
+     * fields — reusing one makes `focusField()` target the core field instead.
+     */
     name: string;
     /** Visible label (already translated; RegisterForm does not apply `t()` here). */
     label: string;
@@ -21,7 +25,13 @@ export interface RegisterFieldConfig {
     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 for FieldInput-rendered extras, 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/RegisterForm/_internal/register-form-utils.d.ts

@@ -1,7 +1,24 @@
 import type { RegisterFieldConfig, RegisterFormData, RegisterFormValidationError } from "./register-form-types.js";
 import type { TranslateFn } from "../../../types.js";
-export declare function validateRegisterForm(data: RegisterFormData, t: TranslateFn, extraFields?: RegisterFieldConfig[], options?: {
+/** Options for {@link validateRegisterForm}. Mirror the same-named props. */
+export interface ValidateRegisterFormOptions {
+    /** Validate the email field. Default: true */
+    showEmail?: boolean;
+    /** Validate the password field. Default: true */
+    showPassword?: boolean;
+    /** Validate the confirm field. Ignored when `showPassword` is false. Default: true */
     showPasswordConfirm?: boolean;
+    /** Minimum password length. Default: 8 */
     passwordMinLength?: number;
-}): RegisterFormValidationError[];
+}
+/**
+ * Validate a `RegisterFormData` shape. Exported so consumers running their own
+ * submit handler can reuse the exact same rules `RegisterForm` applies. `t`
+ * defaults to the built-in English strings.
+ *
+ * `options.showEmail` / `options.showPassword` mirror the same-named props:
+ * a field that is not rendered is not validated (identity-first / passwordless
+ * signup, where the credential is established outside the form).
+ */
+export declare function validateRegisterForm(data: RegisterFormData, t?: TranslateFn, extraFields?: RegisterFieldConfig[], options?: ValidateRegisterFormOptions): RegisterFormValidationError[];
 export declare function createEmptyRegisterFormData(): RegisterFormData;

package/dist/components/RegisterForm/_internal/register-form-utils.js

@@ -1,24 +1,41 @@
+import { t_default } from "./register-form-i18n-defaults.js";
 const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-export function validateRegisterForm(data, t, extraFields = [], options = {}) {
-    const { showPasswordConfirm = true, passwordMinLength = 8 } = options;
+/**
+ * Validate a `RegisterFormData` shape. Exported so consumers running their own
+ * submit handler can reuse the exact same rules `RegisterForm` applies. `t`
+ * defaults to the built-in English strings.
+ *
+ * `options.showEmail` / `options.showPassword` mirror the same-named props:
+ * a field that is not rendered is not validated (identity-first / passwordless
+ * signup, where the credential is established outside the form).
+ */
+export function validateRegisterForm(data, t = t_default, extraFields = [], options = {}) {
+    const { showEmail = true, showPassword = true, showPasswordConfirm = true, passwordMinLength = 8, } = options;
     const errors = [];
-    const trimmedEmail = data.email.trim();
-    if (!trimmedEmail) {
-        errors.push({ field: "email", message: t("register_form.email_required") });
-    }
-    else if (!EMAIL_RE.test(trimmedEmail)) {
-        errors.push({ field: "email", message: t("register_form.email_invalid") });
-    }
-    if (!data.password) {
-        errors.push({ field: "password", message: t("register_form.password_required") });
+    if (showEmail) {
+        const trimmedEmail = (data.email ?? "").trim();
+        if (!trimmedEmail) {
+            errors.push({ field: "email", message: t("register_form.email_required") });
+        }
+        else if (!EMAIL_RE.test(trimmedEmail)) {
+            errors.push({ field: "email", message: t("register_form.email_invalid") });
+        }
     }
-    else if (data.password.length < passwordMinLength) {
-        errors.push({
-            field: "password",
-            message: t("register_form.password_too_short", { min: passwordMinLength }),
-        });
+    if (showPassword) {
+        if (!data.password) {
+            errors.push({
+                field: "password",
+                message: t("register_form.password_required"),
+            });
+        }
+        else if (data.password.length < passwordMinLength) {
+            errors.push({
+                field: "password",
+                message: t("register_form.password_too_short", { min: passwordMinLength }),
+            });
+        }
     }
-    if (showPasswordConfirm) {
+    if (showPassword && showPasswordConfirm) {
         if (!data.passwordConfirm) {
             errors.push({
                 field: "passwordConfirm",

package/dist/components/RegisterForm/index.css

@@ -10,6 +10,14 @@
 	--stuic-register-form-social-divider-line-color: var(--stuic-color-border);
 	--stuic-register-form-social-divider-font-size: var(--text-sm);
 	--stuic-register-form-social-divider-margin-bottom: 0.75rem;
+
+	/* Social login section when placed above the credentials (socialPosition="top") */
+	--stuic-register-form-social-margin-bottom: 1rem;
+	--stuic-register-form-social-divider-margin-top: 0.75rem;
+
+	/* credentialsSlot wrapper + the per-field rhythm inside the form */
+	--stuic-register-form-credentials-margin-bottom: 1rem;
+	--stuic-register-form-field-margin-bottom: 1rem;
 }
 
 @layer components {
@@ -24,6 +32,13 @@
 		margin-bottom: 1.5rem;
 	}
 
+	/* credentialsSlot wrapper — the form is a zero-gap flex column, so consumer
+	   content dropped in at the credentials position needs the same bottom
+	   rhythm the fields get. */
+	.stuic-register-form-credentials {
+		margin-bottom: var(--stuic-register-form-credentials-margin-bottom);
+	}
+
 	/* Social login container */
 	.stuic-register-form-social {
 		margin-top: var(--stuic-register-form-social-margin-top);
@@ -52,9 +67,25 @@
 		flex-direction: column;
 		gap: var(--stuic-register-form-social-gap);
 	}
+
+	/* socialPosition="top" — the block sits above the credentials, so the margin
+	   and the divider both mirror. `[data-position="bottom"]` is intentionally
+	   unstyled: the default render stays byte-for-byte what it always was. */
+	.stuic-register-form-social[data-position="top"] {
+		margin-top: 0;
+		margin-bottom: var(--stuic-register-form-social-margin-bottom);
+	}
+
+	.stuic-register-form-social[data-position="top"] .stuic-register-form-social-divider {
+		margin-top: var(--stuic-register-form-social-divider-margin-top);
+		margin-bottom: 0;
+	}
 }
 
-/* Tighten default FieldInput bottom margin (mb-8 → 1rem) inside the form */
+/* Tighten default FieldInput bottom margin (mb-8 → 1rem) inside the form.
+   Deliberately unlayered so it outranks the utility class it replaces — which
+   also means a `class` passed through `emailFieldProps` can't override it, so
+   the value is a token instead of a literal. */
 .stuic-register-form .stuic-input {
-	margin-bottom: 1rem;
+	margin-bottom: var(--stuic-register-form-field-margin-bottom);
 }

package/dist/components/RegisterForm/index.d.ts

@@ -1,4 +1,5 @@
 export { default as RegisterForm, type Props as RegisterFormProps, } from "./RegisterForm.svelte";
 export { default as RegisterFormModal, type Props as RegisterFormModalProps, } from "./RegisterFormModal.svelte";
-export { createEmptyRegisterFormData } from "./_internal/register-form-utils.js";
+export { createEmptyRegisterFormData, validateRegisterForm, } from "./_internal/register-form-utils.js";
+export type { ValidateRegisterFormOptions } from "./_internal/register-form-utils.js";
 export type { RegisterFormData, RegisterFormValidationError, RegisterFieldConfig, } from "./_internal/register-form-types.js";

package/dist/components/RegisterForm/index.js

@@ -1,3 +1,3 @@
 export { default as RegisterForm, } from "./RegisterForm.svelte";
 export { default as RegisterFormModal, } from "./RegisterFormModal.svelte";
-export { createEmptyRegisterFormData } from "./_internal/register-form-utils.js";
+export { createEmptyRegisterFormData, validateRegisterForm, } from "./_internal/register-form-utils.js";

package/dist/utils/field-errors.svelte.d.ts

@@ -0,0 +1,114 @@
+import type { ValidatableField } from "./validate-fields.js";
+/**
+ * Minimal shape of a `errors` entry — every STUIC form's `*ValidationError`
+ * type structurally satisfies it.
+ */
+export interface FieldError {
+    field: string;
+    message: string;
+}
+export interface ExternalFieldErrorsOptions<E extends FieldError> {
+    /** The consumer-supplied `errors` prop. Read reactively — pass a getter. */
+    errors: () => E[];
+    /**
+     * Is this error's field currently rendered — i.e. is there something on
+     * screen the user could edit to answer it?
+     *
+     * Fields that are not (a field the consumer renders itself from a slot, or
+     * one switched off by a `show*` prop) keep the original behavior: they apply
+     * until the consumer drops them from `errors`. Auto-clearing those would let
+     * the form post past a block the consumer set deliberately — an unchecked
+     * terms box, a failed captcha, a pending availability check.
+     */
+    isRendered: (field: string) => boolean;
+    /** Comparable current value of a rendered field. */
+    valueOf: (field: string) => string;
+}
+export interface ExternalFieldErrors<E extends FieldError> {
+    /** The subset of `errors` that still applies — stale entries filtered out. */
+    readonly live: E[];
+    /**
+     * Mark that a server round-trip is starting. Call it wherever the form hands
+     * data to the consumer (its `onSubmit`, and its exported `validate()` for
+     * consumers posting from their own handler).
+     */
+    markSubmitted(): void;
+}
+/**
+ * Give a form's consumer-supplied `errors` prop a lifecycle.
+ *
+ * `errors` is consumer-owned: a form can render it but cannot clear it. Taken
+ * literally that wedges the form permanently — the field's `customValidator`
+ * keeps reporting the server error whatever the user types, so
+ * `onSubmitValidityCheck` routes every later submit to `submit_invalid` and
+ * `onSubmit` never fires again, *including* the consumer's own handler that
+ * would have cleared the errors. (Forms without that action hit the same wall
+ * through their `externalErrors.length === 0` submit gate.)
+ *
+ * So: remember the value each field held when a set of errors was delivered.
+ * An error on a rendered field stays live while that field still holds that
+ * value and goes stale once the user edits it — dropped from the inline
+ * messages and from the submit gate, the same lifecycle internal validation
+ * errors already have. Typing the rejected value back in makes it live again,
+ * which is correct: that exact value is known-bad.
+ *
+ * Two details that look like over-engineering and are not:
+ *
+ * - Delivery is detected by the errors' **content**, never by array identity.
+ *   Consumers routinely pass an inline literal or a freshly derived array whose
+ *   identity changes on every parent re-render; re-snapshotting mid-typing would
+ *   resurrect the error and restore the deadlock.
+ * - Because of that, an identical error redelivered after a resubmit would look
+ *   like the previous, already-answered one. `markSubmitted()` disambiguates:
+ *   the next delivery after it counts as fresh even when byte-identical.
+ *
+ * Must be called during component initialization (it registers an `$effect`).
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   let { errors: externalErrors = [], formData = $bindable(...) } = $props();
+ *
+ *   const external = createExternalFieldErrors({
+ *     errors: () => externalErrors,
+ *     isRendered: (f) => f === "email" || f === "password",
+ *     valueOf: (f) => (f === "email" ? formData.email : formData.password) ?? "",
+ *   });
+ *
+ *   function handleSubmitValid() {
+ *     // ...
+ *     if (!validationErrors.length && !external.live.length) {
+ *       external.markSubmitted();
+ *       onSubmit(formData);
+ *     }
+ *   }
+ * </script>
+ * ```
+ */
+export declare function createExternalFieldErrors<E extends FieldError>(options: ExternalFieldErrorsOptions<E>): ExternalFieldErrors<E>;
+/**
+ * Render a field's error message as soon as it exists, instead of waiting for
+ * the user's next interaction.
+ *
+ * Inline messages come from each field's own validation run, and the `validate`
+ * action fires on `change` / first blur. An error that appears *after* the
+ * validators last ran therefore paints nothing:
+ *
+ * - a form's own validator result is computed on `submit_valid`, i.e. after
+ *   `onSubmitValidityCheck` has already re-run every field's validator, so a
+ *   rule with no DOM equivalent (a password mismatch, a custom validator, an
+ *   email that satisfies `type="email"` but not a stricter regex) produced a
+ *   completely silent first click — the CTA appeared to do nothing;
+ * - a server `errors` delivery lands once the submit is over, so it stayed
+ *   invisible until the user clicked again.
+ *
+ * Only fields gaining an error are re-validated; clearing is left to the field's
+ * own next change/blur, so fixing one field doesn't wipe the messages still
+ * standing on its siblings.
+ *
+ * Must be called during component initialization (it registers an `$effect`).
+ *
+ * @param errors - all currently applicable errors (internal + live external)
+ * @param fieldByName - resolves a field name to its rendered component, if any
+ */
+export declare function repaintFieldErrors(errors: () => FieldError[], fieldByName: (field: string) => ValidatableField | undefined): void;