@marianmeres/stuic 3.86.0 → 3.87.0

package/dist/actions/validate.svelte.d.ts

@@ -81,6 +81,18 @@ export interface ValidateOptions {
     customValidator?: (value: unknown, context: Record<string, unknown> | undefined, el: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement) => string | undefined;
     on?: "input" | "change";
     setValidationResult?: (res: ValidationResult) => void;
+    /**
+     * Receives a reference to the action's internal validator function so the
+     * host component can trigger validation imperatively (e.g., on submit,
+     * without waiting for the user to focus/blur or change a value).
+     *
+     * Called whenever the action's `$effect` re-runs — the host should store
+     * the latest reference. Invoking the function runs the exact same code
+     * path the change/blur listeners do (no synthetic DOM events).
+     *
+     * Pair with `setValidationResult` to read the new result after invoking.
+     */
+    setDoValidate?: (doValidate: () => void) => void;
     t?: false | ReasonTranslate;
 }
 /**
@@ -146,10 +158,18 @@ export interface ValidateOptions {
  * validate.t = (reason, value, fallback) => translations[reason] ?? fallback;
  * ```
  *
- * **Hidden Input Limitation**: Browsers don't populate `el.validationMessage`
- * for hidden inputs (`type="hidden"`) even when `setCustomValidity()` is called.
- * This action works around this by preserving the `customValidator` return value
- * and using it directly as the error message fallback.
+ * **Hidden Input Limitations** (two distinct issues, both relevant when wrapping
+ * `<input type="hidden">` for form-data participation):
+ *
+ * 1. Browsers don't populate `el.validationMessage` for hidden inputs even when
+ *    `setCustomValidity()` is called. This action works around it by preserving
+ *    the `customValidator` return value and using it directly as the error
+ *    message fallback.
+ * 2. Per the HTML spec, hidden inputs are **barred from constraint validation**
+ *    entirely. `validity.valueMissing` stays `false` regardless of the
+ *    `required` attribute, so `required` is a silent no-op. STUIC's hidden-input
+ *    Field components (`FieldPhoneNumber`, `FieldCountry`, `FieldObject`, etc.)
+ *    enforce `required` themselves inside their `customValidator`.
  */
 export declare function validate(el: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement, fn?: () => boolean | ValidateOptions): void;
 export declare namespace validate {

package/dist/actions/validate.svelte.js

@@ -128,16 +128,24 @@ const KNOWN_REASONS = [
  * validate.t = (reason, value, fallback) => translations[reason] ?? fallback;
  * ```
  *
- * **Hidden Input Limitation**: Browsers don't populate `el.validationMessage`
- * for hidden inputs (`type="hidden"`) even when `setCustomValidity()` is called.
- * This action works around this by preserving the `customValidator` return value
- * and using it directly as the error message fallback.
+ * **Hidden Input Limitations** (two distinct issues, both relevant when wrapping
+ * `<input type="hidden">` for form-data participation):
+ *
+ * 1. Browsers don't populate `el.validationMessage` for hidden inputs even when
+ *    `setCustomValidity()` is called. This action works around it by preserving
+ *    the `customValidator` return value and using it directly as the error
+ *    message fallback.
+ * 2. Per the HTML spec, hidden inputs are **barred from constraint validation**
+ *    entirely. `validity.valueMissing` stays `false` regardless of the
+ *    `required` attribute, so `required` is a silent no-op. STUIC's hidden-input
+ *    Field components (`FieldPhoneNumber`, `FieldCountry`, `FieldObject`, etc.)
+ *    enforce `required` themselves inside their `customValidator`.
  */
 export function validate(el, fn) {
     $effect(() => {
         //
         const fnResult = fn?.() ?? {};
-        const { enabled, context, customValidator, on = "change", setValidationResult, t, } = typeof fnResult === "boolean" ? { enabled: !!fnResult } : fnResult;
+        const { enabled, context, customValidator, on = "change", setValidationResult, setDoValidate, t, } = typeof fnResult === "boolean" ? { enabled: !!fnResult } : fnResult;
         //
         const _t = (reason, value, fallback) => {
             // explicit false
@@ -218,6 +226,11 @@ export function validate(el, fn) {
             });
             // });
         };
+        // Expose the current validator to the host so it can trigger validation
+        // imperatively (e.g., on submit). The closure captures the current
+        // `enabled` / `customValidator` / `context` / `t`, so re-running the
+        // effect with new options updates the exposed function in lockstep.
+        setDoValidate?.(_doValidate);
         el.addEventListener(on, _doValidate);
         //
         let _touchCount = 0;

package/dist/components/EmailVerifyForm/EmailVerifyForm.svelte

@@ -201,6 +201,27 @@
 	);
 
 	let submitDisabled = $derived(code.length !== codeLength || isSubmitting);
+
+	// Imperative API ----------------------------------------------------------
+	// EmailVerifyForm uses OtpInput rather than validateAction-based fields, so
+	// "validation" here is just "is the code complete?". Exposed for parity
+	// with LoginForm / RegisterForm so consumers (and LoginOrRegisterForm) can
+	// call `.validate()` regardless of which sub-form is active.
+
+	/** Returns true when the OTP code is the expected length. */
+	export function validate(): boolean {
+		return code.length === codeLength;
+	}
+
+	/**
+	 * Scroll the form into view if the code is incomplete. Returns true if
+	 * a scroll was performed.
+	 */
+	export function scrollToFirstError(opts?: ScrollIntoViewOptions): boolean {
+		if (validate()) return false;
+		formEl?.scrollIntoView?.({ behavior: "smooth", block: "center", ...opts });
+		return true;
+	}
 </script>
 
 <form bind:this={formEl} class={_class} onsubmit={handleFormSubmit} {...rest}>

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

@@ -49,6 +49,9 @@ export interface Props extends Omit<HTMLAttributes<HTMLFormElement>, "children">
     class?: string;
     el?: HTMLFormElement;
 }
-declare const EmailVerifyForm: import("svelte").Component<Props, {}, "el">;
+declare const EmailVerifyForm: import("svelte").Component<Props, {
+    validate: () => boolean;
+    scrollToFirstError: (opts?: ScrollIntoViewOptions) => boolean;
+}, "el">;
 type EmailVerifyForm = ReturnType<typeof EmailVerifyForm>;
 export default EmailVerifyForm;

package/dist/components/Input/FieldAssets.svelte

@@ -187,7 +187,8 @@
 		required = false,
 		disabled = false,
 		//
-		validate,
+		// Renamed local binding to avoid collision with `export function validate()` below.
+		validate: validateProp,
 		//
 		labelAfter,
 		below,
@@ -251,6 +252,9 @@
 	let parentHiddenInputEl: HTMLInputElement | undefined = $state();
 	let hasLabel = $derived(isTHCNotEmpty(label) || typeof label === "function");
 	let inputEl = $state<HTMLInputElement>()!;
+	// Outer wrapper for scrollIntoView and focus targeting.
+	let wrapEl: HTMLDivElement | undefined = $state();
+	let hiddenInputEl: HTMLInputElement | undefined = $state();
 	let assetsPreview: AssetsPreview = $state()!;
 
 	let assets: FieldAsset[] = $derived(parseValue(value));
@@ -270,6 +274,38 @@
 	let validation: ValidationResult | undefined = $state();
 	const setValidationResult = (res: ValidationResult) => (validation = res);
 
+	let _doValidate: (() => void) | undefined = $state();
+
+	/** Trigger validation now. Renders the inline message if invalid. */
+	export function validate(): ValidationResult | undefined {
+		_doValidate?.();
+		return validation;
+	}
+
+	/** Clear the inline validation message and reset `setCustomValidity`. */
+	export function clearValidation(): void {
+		validation = undefined;
+		hiddenInputEl?.setCustomValidity?.("");
+	}
+
+	/** Current validation state, or undefined if validator has never run. */
+	export function getValidation(): ValidationResult | undefined {
+		return validation;
+	}
+
+	/**
+	 * Focus the visible dropzone wrapper. The hidden file/validation inputs
+	 * cannot be focused directly.
+	 */
+	export function focus(): void {
+		wrapEl?.focus?.();
+	}
+
+	/** Scroll the field into view. Defaults to smooth + center. */
+	export function scrollIntoView(opts?: ScrollIntoViewOptions): void {
+		wrapEl?.scrollIntoView?.({ behavior: "smooth", block: "center", ...opts });
+	}
+
 	//
 	let wrappedValidate: Omit<ValidateOptions, "setValidationResult"> = $derived({
 		enabled: true,
@@ -285,12 +321,13 @@
 			// normally, with other fieldtypes, we would continue with provided validator:
 			// return (validate as any)?.customValidator?.(value, context, el) || "";
 			// but not here, we just warn
-			if ((validate as any)?.customValidator) {
+			if ((validateProp as any)?.customValidator) {
 				console.warn("Custom validator was provided, but is ignored in <FieldAssets />");
 			}
 			return "";
 		},
 		setValidationResult,
+		setDoValidate: (fn: () => void) => (_doValidate = fn),
 	});
 
 	//
@@ -404,6 +441,8 @@
 
 <div
 	class={twMerge("w-full stuic-field-assets mb-8", classWrap)}
+	bind:this={wrapEl}
+	tabindex="-1"
 	use:highlightDragover={() => ({
 		enabled: typeof processAssets === "function",
 		classes: ["outline-dashed outline-2 outline-(--stuic-color-border)"],
@@ -516,7 +555,13 @@
 
 <input type="file" bind:this={inputEl} multiple style="display: none" {accept} />
 <!-- hack to be able to validate the conventional way -->
-<input type="hidden" {name} {value} use:validateAction={() => wrappedValidate} />
+<input
+	type="hidden"
+	{name}
+	{value}
+	bind:this={hiddenInputEl}
+	use:validateAction={() => wrappedValidate}
+/>
 
 <AssetsPreview
 	bind:this={assetsPreview}

package/dist/components/Input/FieldAssets.svelte.d.ts

@@ -1,5 +1,5 @@
 import { type Snippet } from "svelte";
-import { type ValidateOptions } from "../../actions/validate.svelte.js";
+import { type ValidateOptions, type ValidationResult } from "../../actions/validate.svelte.js";
 import type { TranslateFn } from "../../types.js";
 import { NotificationsStack } from "../Notifications/notifications-stack.svelte.js";
 import { type THC } from "../Thc/Thc.svelte";
@@ -63,6 +63,12 @@ export interface Props extends InputWrapClassProps, Record<string, any> {
     isLoading?: boolean;
     classWrap?: string;
 }
-declare const FieldAssets: import("svelte").Component<Props, {}, "value">;
+declare const FieldAssets: import("svelte").Component<Props, {
+    validate: () => ValidationResult | undefined;
+    clearValidation: () => void;
+    getValidation: () => ValidationResult | undefined;
+    focus: () => void;
+    scrollIntoView: (opts?: ScrollIntoViewOptions) => void;
+}, "value">;
 type FieldAssets = ReturnType<typeof FieldAssets>;
 export default FieldAssets;

package/dist/components/Input/FieldCheckbox.svelte

@@ -48,7 +48,8 @@
 		disabled,
 		renderSize = "md",
 		description,
-		validate,
+		// Renamed local binding to avoid collision with `export function validate()` below.
+		validate: validateProp,
 		class: classProp,
 		classInputBox,
 		classInput,
@@ -64,6 +65,35 @@
 	let validation: ValidationResult | undefined = $state();
 	const setValidationResult = (res: ValidationResult) => (validation = res);
 
+	let _doValidate: (() => void) | undefined = $state();
+
+	/** Trigger validation now. Renders the inline message if invalid. */
+	export function validate(): ValidationResult | undefined {
+		_doValidate?.();
+		return validation;
+	}
+
+	/** Clear the inline validation message and reset `setCustomValidity`. */
+	export function clearValidation(): void {
+		validation = undefined;
+		input?.setCustomValidity?.("");
+	}
+
+	/** Current validation state, or undefined if validator has never run. */
+	export function getValidation(): ValidationResult | undefined {
+		return validation;
+	}
+
+	/** Focus the checkbox element. */
+	export function focus(): void {
+		input?.focus?.();
+	}
+
+	/** Scroll the field into view. Defaults to smooth + center. */
+	export function scrollIntoView(opts?: ScrollIntoViewOptions): void {
+		input?.scrollIntoView?.({ behavior: "smooth", block: "center", ...opts });
+	}
+
 	//
 	let invalid = $derived(validation && !validation?.valid);
 	let idDesc = getId();
@@ -99,9 +129,10 @@
 			aria-checked={checked}
 			aria-describedby={description ? idDesc : undefined}
 			use:validateAction={() => ({
-				enabled: !!validate,
-				...(typeof validate === "boolean" ? {} : validate),
+				enabled: validateProp !== false,
+				...(typeof validateProp === "boolean" ? {} : validateProp),
 				setValidationResult,
+				setDoValidate: (fn) => (_doValidate = fn),
 			})}
 			class={twMerge(classInput)}
 			{required}

package/dist/components/Input/FieldCheckbox.svelte.d.ts

@@ -24,6 +24,13 @@ export interface Props extends HTMLInputAttributes {
     classValidationBox?: string;
     style?: string;
 }
-declare const FieldCheckbox: import("svelte").Component<Props, {}, "input" | "checked">;
+import { type ValidationResult } from "../../actions/validate.svelte.js";
+declare const FieldCheckbox: import("svelte").Component<Props, {
+    validate: () => ValidationResult | undefined;
+    clearValidation: () => void;
+    getValidation: () => ValidationResult | undefined;
+    focus: () => void;
+    scrollIntoView: (opts?: ScrollIntoViewOptions) => void;
+}, "input" | "checked">;
 type FieldCheckbox = ReturnType<typeof FieldCheckbox>;
 export default FieldCheckbox;

package/dist/components/Input/FieldCountry.svelte

@@ -68,6 +68,7 @@
 </script>
 
 <script lang="ts">
+	import { tick } from "svelte";
 	import {
 		validate as validateAction,
 		type ValidationResult,
@@ -102,7 +103,8 @@
 		description,
 		class: classProp,
 		renderSize = "md",
-		validate,
+		// Renamed local binding to avoid collision with `export function validate()` below.
+		validate: validateProp,
 		//
 		labelAfter,
 		inputBefore,
@@ -136,6 +138,39 @@
 	let validation: ValidationResult | undefined = $state();
 	const setValidationResult = (res: ValidationResult) => (validation = res);
 
+	let _doValidate: (() => void) | undefined = $state();
+
+	/** Trigger validation now. Renders the inline message if invalid. */
+	export function validate(): ValidationResult | undefined {
+		_doValidate?.();
+		return validation;
+	}
+
+	/** Clear the inline validation message and reset `setCustomValidity`. */
+	export function clearValidation(): void {
+		validation = undefined;
+		hiddenInputEl?.setCustomValidity?.("");
+	}
+
+	/** Current validation state, or undefined if validator has never run. */
+	export function getValidation(): ValidationResult | undefined {
+		return validation;
+	}
+
+	/** Focus the visible dropdown trigger button. */
+	export function focus(): void {
+		triggerEl?.focus?.();
+	}
+
+	/** Scroll the field into view. Defaults to smooth + center. */
+	export function scrollIntoView(opts?: ScrollIntoViewOptions): void {
+		triggerEl?.scrollIntoView?.({
+			behavior: "smooth",
+			block: "center",
+			...opts,
+		});
+	}
+
 	function localizedName(c: Country): string {
 		return countryNames?.[c.iso] ?? c.name;
 	}
@@ -174,8 +209,14 @@
 			onSelect: () => {
 				value = c.iso;
 				onChange?.(c.iso);
-				// Trigger change on hidden input so validation runs.
-				hiddenInputEl?.dispatchEvent(new Event("change", { bubbles: true }));
+				// Wait one tick so Svelte flushes the `value` binding onto the
+				// hidden input's DOM attribute BEFORE we fire the change event.
+				// Without this, the validate action reads the stale `el.value`
+				// (still empty) on the first selection — the required-check then
+				// keeps the inline error visible until the second selection.
+				tick().then(() => {
+					hiddenInputEl?.dispatchEvent(new Event("change", { bubbles: true }));
+				});
 			},
 		};
 	}
@@ -308,19 +349,35 @@
 	</DropdownMenu>
 </InputWrap>
 
-<!-- Hidden input for form submission + validation -->
-{#if name}
+<!-- Hidden input for form submission + validation.
+     Rendered whenever validation is enabled (default) OR `name` is set, so
+     imperative `validate()` works even when the field is used outside a
+     <form> / without a name. A hidden input without `name` is skipped by
+     FormData per the HTML spec, so this is invisible to form submission. -->
+{#if name || validateProp !== false}
 	<input
 		type="hidden"
 		{name}
 		value={value ?? ""}
 		bind:this={hiddenInputEl}
 		use:validateAction={() => {
-			const customOpts = typeof validate === "object" && validate ? validate : {};
+			const customOpts =
+				typeof validateProp === "object" && validateProp ? validateProp : {};
+			const userValidator = customOpts.customValidator;
 			return {
-				enabled: validate !== false,
+				enabled: validateProp !== false,
 				...customOpts,
+				// Hidden inputs are barred from native constraint validation, so
+				// `required` on the element itself is a no-op. We enforce it here
+				// instead, then fall through to the consumer's customValidator.
+				customValidator(val, ctx, el) {
+					if (required && (val == null || val === "")) {
+						return "This field requires attention. Please review and try again.";
+					}
+					return userValidator?.(val, ctx, el) || "";
+				},
 				setValidationResult,
+				setDoValidate: (fn) => (_doValidate = fn),
 			};
 		}}
 		{required}

package/dist/components/Input/FieldCountry.svelte.d.ts

@@ -54,6 +54,13 @@ export interface Props extends InputWrapClassProps, Record<string, any> {
     style?: string;
     t?: TranslateFn;
 }
-declare const FieldCountry: import("svelte").Component<Props, {}, "value">;
+import { type ValidationResult } from "../../actions/validate.svelte.js";
+declare const FieldCountry: import("svelte").Component<Props, {
+    validate: () => ValidationResult | undefined;
+    clearValidation: () => void;
+    getValidation: () => ValidationResult | undefined;
+    focus: () => void;
+    scrollIntoView: (opts?: ScrollIntoViewOptions) => void;
+}, "value">;
 type FieldCountry = ReturnType<typeof FieldCountry>;
 export default FieldCountry;

package/dist/components/Input/FieldFile.svelte

@@ -64,7 +64,8 @@
 		required = false,
 		disabled = false,
 		//
-		validate,
+		// Renamed local binding to avoid collision with `export function validate()` below.
+		validate: validateProp,
 		//
 		labelAfter,
 		inputBefore,
@@ -95,6 +96,35 @@
 	let validation: ValidationResult | undefined = $state();
 	const setValidationResult = (res: ValidationResult) => (validation = res);
 
+	let _doValidate: (() => void) | undefined = $state();
+
+	/** Trigger validation now. Renders the inline message if invalid. */
+	export function validate(): ValidationResult | undefined {
+		_doValidate?.();
+		return validation;
+	}
+
+	/** Clear the inline validation message and reset `setCustomValidity`. */
+	export function clearValidation(): void {
+		validation = undefined;
+		input?.setCustomValidity?.("");
+	}
+
+	/** Current validation state, or undefined if validator has never run. */
+	export function getValidation(): ValidationResult | undefined {
+		return validation;
+	}
+
+	/** Focus the underlying `<input type="file">` element. */
+	export function focus(): void {
+		input?.focus?.();
+	}
+
+	/** Scroll the field into view. Defaults to smooth + center. */
+	export function scrollIntoView(opts?: ScrollIntoViewOptions): void {
+		input?.scrollIntoView?.({ behavior: "smooth", block: "center", ...opts });
+	}
+
 	// $inspect(files);
 </script>
 
@@ -134,9 +164,10 @@
 			class={twMerge("block w-full", classInput)}
 			use:highlightDragover={() => ({ classes: ["outline-dashed"] })}
 			use:validateAction={() => ({
-				enabled: !!validate,
-				...(typeof validate === "boolean" ? {} : validate),
+				enabled: validateProp !== false,
+				...(typeof validateProp === "boolean" ? {} : validateProp),
 				setValidationResult,
+				setDoValidate: (fn) => (_doValidate = fn),
 			})}
 			{multiple}
 			{tabindex}

package/dist/components/Input/FieldFile.svelte.d.ts

@@ -33,6 +33,13 @@ export interface Props extends HTMLInputAttributes, InputWrapClassProps, Record<
     classFileList?: string;
     style?: string;
 }
-declare const FieldFile: import("svelte").Component<Props, {}, "input" | "files">;
+import { type ValidationResult } from "../../actions/validate.svelte.js";
+declare const FieldFile: import("svelte").Component<Props, {
+    validate: () => ValidationResult | undefined;
+    clearValidation: () => void;
+    getValidation: () => ValidationResult | undefined;
+    focus: () => void;
+    scrollIntoView: (opts?: ScrollIntoViewOptions) => void;
+}, "input" | "files">;
 type FieldFile = ReturnType<typeof FieldFile>;
 export default FieldFile;

package/dist/components/Input/FieldInput.svelte

@@ -67,7 +67,10 @@
 		required = false,
 		disabled = false,
 		//
-		validate,
+		// Renamed binding because `validate` is also the name of the exported
+		// imperative method below — destructuring under the same name would
+		// collide with `export function validate()` in the script scope.
+		validate: validateProp,
 		//
 		labelAfter,
 		inputBefore,
@@ -97,6 +100,42 @@
 	//
 	let validation: ValidationResult | undefined = $state();
 	const setValidationResult = (res: ValidationResult) => (validation = res);
+
+	// Imperative API. The validate action re-assigns `_doValidate` on every
+	// $effect run (whenever options change), so the exported `validate()`
+	// always invokes the current closure.
+	let _doValidate: (() => void) | undefined = $state();
+
+	/**
+	 * Trigger validation now. Same code path as the change/blur listeners.
+	 * Renders the inline validation message if invalid. Useful from submit
+	 * handlers where the user may not have touched every field.
+	 */
+	export function validate(): ValidationResult | undefined {
+		_doValidate?.();
+		return validation;
+	}
+
+	/** Clear the inline validation message and reset `setCustomValidity`. */
+	export function clearValidation(): void {
+		validation = undefined;
+		input?.setCustomValidity?.("");
+	}
+
+	/** Current validation state, or undefined if validator has never run. */
+	export function getValidation(): ValidationResult | undefined {
+		return validation;
+	}
+
+	/** Focus the underlying `<input>` element. */
+	export function focus(): void {
+		input?.focus?.();
+	}
+
+	/** Scroll the field into view. Defaults to smooth + center. */
+	export function scrollIntoView(opts?: ScrollIntoViewOptions): void {
+		input?.scrollIntoView?.({ behavior: "smooth", block: "center", ...opts });
+	}
 </script>
 
 <InputWrap
@@ -142,9 +181,10 @@
 			...(typeof useTypeahead === "boolean" ? {} : useTypeahead),
 		})}
 		use:validateAction={() => ({
-			enabled: !!validate,
-			...(typeof validate === "boolean" ? {} : validate),
+			enabled: validateProp !== false,
+			...(typeof validateProp === "boolean" ? {} : validateProp),
 			setValidationResult,
+			setDoValidate: (fn) => (_doValidate = fn),
 		})}
 		{tabindex}
 		{required}

package/dist/components/Input/FieldInput.svelte.d.ts

@@ -34,6 +34,13 @@ export interface Props extends HTMLInputAttributes, InputWrapClassProps, Record<
     classInput?: string;
     style?: string;
 }
-declare const FieldInput: import("svelte").Component<Props, {}, "value" | "input">;
+import { type ValidationResult } from "../../actions/validate.svelte.js";
+declare const FieldInput: import("svelte").Component<Props, {
+    validate: () => ValidationResult | undefined;
+    clearValidation: () => void;
+    getValidation: () => ValidationResult | undefined;
+    focus: () => void;
+    scrollIntoView: (opts?: ScrollIntoViewOptions) => void;
+}, "value" | "input">;
 type FieldInput = ReturnType<typeof FieldInput>;
 export default FieldInput;