@marianmeres/stuic 3.85.0 → 3.87.0

package/dist/components/Switch/Switch.svelte

@@ -58,7 +58,8 @@
 		off,
 		onclick,
 		preHook,
-		validate,
+		// Renamed local binding to avoid collision with `export function validate()` below.
+		validate: validateProp,
 		setValidationResult,
 		...rest
 	}: Props = $props();
@@ -89,6 +90,39 @@
 		checkbox.dispatchEvent(new Event("change", { bubbles: true, cancelable: true }));
 		wrap.focus();
 	}
+
+	//
+	let _doValidate: (() => void) | undefined = $state();
+	// Local copy of the last validation result so getValidation() works even
+	// when no external setValidationResult was provided.
+	let _validation: ValidationResult | undefined = $state();
+
+	/** Trigger validation now. Reaches the parent via `setValidationResult`. */
+	export function validate(): ValidationResult | undefined {
+		_doValidate?.();
+		return _validation;
+	}
+
+	/** Clear the inline validation message and reset `setCustomValidity`. */
+	export function clearValidation(): void {
+		_validation = undefined;
+		checkbox?.setCustomValidity?.("");
+	}
+
+	/** Current validation state. */
+	export function getValidation(): ValidationResult | undefined {
+		return _validation;
+	}
+
+	/** Focus the visual switch wrapper. */
+	export function focus(): void {
+		wrap?.focus?.();
+	}
+
+	/** Scroll the switch into view. */
+	export function scrollIntoView(opts?: ScrollIntoViewOptions): void {
+		wrap?.scrollIntoView?.({ behavior: "smooth", block: "center", ...opts });
+	}
 </script>
 
 <!-- svelte-ignore a11y_no_noninteractive_tabindex -->
@@ -140,9 +174,13 @@
 		{required}
 		{name}
 		use:validateAction={() => ({
-			enabled: !!validate,
-			...(typeof validate === "boolean" ? {} : validate),
-			setValidationResult,
+			enabled: validateProp !== false,
+			...(typeof validateProp === "boolean" ? {} : validateProp),
+			setValidationResult: (res) => {
+				_validation = res;
+				setValidationResult?.(res);
+			},
+			setDoValidate: (fn) => (_doValidate = fn),
 		})}
 		tabindex="-1"
 	/>

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

@@ -29,6 +29,12 @@ export interface Props extends Omit<HTMLLabelAttributes, "children" | "onchange"
     validate?: boolean | Omit<ValidateOptions, "setValidationResult">;
     setValidationResult?: (res: ValidationResult) => void;
 }
-declare const Switch: import("svelte").Component<Props, {}, "button" | "checked">;
+declare const Switch: import("svelte").Component<Props, {
+    validate: () => ValidationResult | undefined;
+    clearValidation: () => void;
+    getValidation: () => ValidationResult | undefined;
+    focus: () => void;
+    scrollIntoView: (opts?: ScrollIntoViewOptions) => void;
+}, "button" | "checked">;
 type Switch = ReturnType<typeof Switch>;
 export default Switch;

package/dist/utils/index.d.ts

@@ -41,3 +41,4 @@ export * from "./tr.js";
 export * from "./tw-merge.js";
 export * from "./ucfirst.js";
 export * from "./unaccent.js";
+export * from "./validate-fields.js";

package/dist/utils/index.js

@@ -41,3 +41,4 @@ export * from "./tr.js";
 export * from "./tw-merge.js";
 export * from "./ucfirst.js";
 export * from "./unaccent.js";
+export * from "./validate-fields.js";

package/dist/utils/validate-fields.d.ts

@@ -0,0 +1,72 @@
+import type { ValidationResult } from "../actions/validate.svelte.js";
+/**
+ * Minimal shape any STUIC field component implements once it exposes the
+ * imperative validate API. Form-level helpers and consumer aggregators consume
+ * this — they don't care what specific field type they're dealing with.
+ *
+ * Every STUIC `Field*` component (FieldInput, FieldPhoneNumber, FieldCountry,
+ * FieldSelect, FieldCheckbox, FieldTextarea, FieldFile, FieldObject,
+ * FieldAssets, FieldInputLocalized, FieldKeyValues, FieldLikeButton,
+ * FieldRadios, FieldSwitch) satisfies this interface via `export function`.
+ */
+export interface ValidatableField {
+    /** Run the validator now. Renders the inline error if invalid. */
+    validate(): ValidationResult | undefined;
+    /** Reset the inline error and clear `el.setCustomValidity`. */
+    clearValidation?(): void;
+    /** Current validation state, or undefined if validator has never run. */
+    getValidation?(): ValidationResult | undefined;
+    /** Focus the visible interactive element. */
+    focus?(): void;
+    /** Scroll the field into view. Defaults to smooth + center. */
+    scrollIntoView?(opts?: ScrollIntoViewOptions): void;
+}
+type FieldArg = ValidatableField | undefined | null;
+/**
+ * Run `validate()` on every provided field. Returns `true` if all are valid.
+ *
+ * `undefined` / `null` entries are skipped so callers can spread conditional
+ * refs without filtering first.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   let nameField = $state();
+ *   let emailField = $state();
+ *
+ *   function handleSubmit() {
+ *     if (!validateAllFields([nameField, emailField])) {
+ *       scrollToFirstInvalidField([nameField, emailField]);
+ *       return;
+ *     }
+ *     // ...submit
+ *   }
+ * </script>
+ * ```
+ */
+export declare function validateAllFields(fields: FieldArg[]): boolean;
+/**
+ * Return the first field whose current validation state is invalid, or
+ * `undefined` if all are valid (or never validated).
+ *
+ * Reads cached state via `getValidation()` — call `validateAllFields()` first
+ * if you need fresh results.
+ */
+export declare function findFirstInvalidField(fields: FieldArg[]): ValidatableField | undefined;
+/**
+ * Scroll the first invalid field into view and (by default) focus it.
+ * Returns `true` if a field was scrolled, `false` if all were valid.
+ *
+ * Call **after** `validateAllFields()` — this reads cached validation state.
+ *
+ * @param fields - Field refs (in display order — first match wins)
+ * @param opts.focus - Whether to also call `focus()` on the field. Default true.
+ * @param opts.behavior - ScrollIntoView behavior. Default `"smooth"`.
+ * @param opts.block - ScrollIntoView block alignment. Default `"center"`.
+ */
+export declare function scrollToFirstInvalidField(fields: FieldArg[], opts?: {
+    focus?: boolean;
+    behavior?: ScrollBehavior;
+    block?: ScrollLogicalPosition;
+}): boolean;
+export {};

package/dist/utils/validate-fields.js

@@ -0,0 +1,73 @@
+/**
+ * Run `validate()` on every provided field. Returns `true` if all are valid.
+ *
+ * `undefined` / `null` entries are skipped so callers can spread conditional
+ * refs without filtering first.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   let nameField = $state();
+ *   let emailField = $state();
+ *
+ *   function handleSubmit() {
+ *     if (!validateAllFields([nameField, emailField])) {
+ *       scrollToFirstInvalidField([nameField, emailField]);
+ *       return;
+ *     }
+ *     // ...submit
+ *   }
+ * </script>
+ * ```
+ */
+export function validateAllFields(fields) {
+    let allValid = true;
+    for (const f of fields) {
+        if (!f)
+            continue;
+        const res = f.validate();
+        if (res && !res.valid)
+            allValid = false;
+    }
+    return allValid;
+}
+/**
+ * Return the first field whose current validation state is invalid, or
+ * `undefined` if all are valid (or never validated).
+ *
+ * Reads cached state via `getValidation()` — call `validateAllFields()` first
+ * if you need fresh results.
+ */
+export function findFirstInvalidField(fields) {
+    for (const f of fields) {
+        if (!f)
+            continue;
+        const v = f.getValidation?.();
+        if (v && !v.valid)
+            return f;
+    }
+    return undefined;
+}
+/**
+ * Scroll the first invalid field into view and (by default) focus it.
+ * Returns `true` if a field was scrolled, `false` if all were valid.
+ *
+ * Call **after** `validateAllFields()` — this reads cached validation state.
+ *
+ * @param fields - Field refs (in display order — first match wins)
+ * @param opts.focus - Whether to also call `focus()` on the field. Default true.
+ * @param opts.behavior - ScrollIntoView behavior. Default `"smooth"`.
+ * @param opts.block - ScrollIntoView block alignment. Default `"center"`.
+ */
+export function scrollToFirstInvalidField(fields, opts) {
+    const field = findFirstInvalidField(fields);
+    if (!field)
+        return false;
+    field.scrollIntoView?.({
+        behavior: opts?.behavior ?? "smooth",
+        block: opts?.block ?? "center",
+    });
+    if (opts?.focus !== false)
+        field.focus?.();
+    return true;
+}

package/docs/domains/actions.md

@@ -64,6 +64,80 @@ Actions using `$effect()` accept a function returning options:
 />
 ```
 
+### Imperative validate() trigger
+
+The `validate` action only runs `_doValidate` in response to user-driven DOM
+events (`change`, first `blur`). On a pristine, never-touched field the inline
+validation message never mounts — which silently breaks any flow that
+pre-populates errors via `customValidator` on a fresh form.
+
+Pass a `setDoValidate` callback to capture a reference to the action's internal
+validator function and trigger it imperatively (e.g., from a submit handler):
+
+```svelte
+<script>
+	let doValidate: (() => void) | undefined = $state();
+
+	function handleSubmit() {
+		// Force every "sleeping" field's validator to run, rendering inline
+		// errors even on fields the user never touched.
+		doValidate?.();
+		// ...check validationResult.valid here, or use validateAllFields().
+	}
+</script>
+
+<input
+	required
+	use:validate={() => ({
+		enabled: true,
+		setValidationResult: (res) => (validationResult = res),
+		setDoValidate: (fn) => (doValidate = fn),
+	})}
+/>
+```
+
+> **You generally don't write this by hand.** Every STUIC `Field*` component
+> already wires `setDoValidate` internally and exposes the result as
+> `export function validate()` on its component reference. See the
+> [Components domain doc](./components.md#imperative-validate-api) for the
+> per-field method list and the [validate-fields utility](./utils.md) for
+> `validateAllFields()` / `scrollToFirstInvalidField()` aggregators.
+
+### Pristine forms and external errors
+
+A common trap: setting an `errors` prop on a brand-new form and expecting the
+inline messages to render. They won't — the `validate` action's
+`customValidator` is only invoked on user events. Two fixes:
+
+1. **Wrap the form in `<form use:onSubmitValidityCheck>`** and listen for
+   `submit_valid` / `submit_invalid` (works for native submit flows).
+2. **Call the field component's imperative `validate()` from your submit
+   handler** (works for any flow — wizards, multi-step, custom CTAs).
+
+### Hidden inputs and `required`
+
+Per the HTML spec, `<input type="hidden">` is *barred from constraint
+validation* — `validity.valueMissing` stays `false` regardless of the
+`required` attribute, and native browser submit blocking is skipped. Several
+STUIC field components (`FieldPhoneNumber`, `FieldCountry`, `FieldObject`,
+`FieldAssets`, `FieldInputLocalized`, `FieldKeyValues`, `FieldLikeButton`)
+use a hidden input to participate in `FormData`, so they each enforce
+`required` themselves inside their `customValidator`:
+
+```ts
+customValidator(val, ctx, el) {
+    if (required && (val == null || val === "")) {
+        return "This field requires attention. Please review and try again.";
+    }
+    return userValidator?.(val, ctx, el) || "";
+}
+```
+
+This means `<FieldCountry required />` and `<FieldPhoneNumber required />`
+correctly fail validation when empty — both through the imperative
+`validate()` path and via `use:onSubmitValidityCheck`. Without this wrap
+they'd silently accept empty values.
+
 ### File Dropzone
 
 ```svelte

package/docs/domains/components.md

@@ -102,6 +102,137 @@
 
 ---
 
+## Imperative validate API
+
+Every `Field*` component that uses the `validate` action exposes a small
+imperative API on its component reference, accessed via `bind:this`. Form
+components (`LoginForm`, `RegisterForm`, `LoginOrRegisterForm`,
+`EmailVerifyForm`) compose those into form-level `validate()` /
+`scrollToFirstError()`.
+
+### Why
+
+The `validate` action only runs on user-driven DOM events (`change`, first
+`blur`). On a pristine, never-touched field the inline `validation-box` never
+mounts — which silently breaks any flow that pre-populates errors via
+`customValidator` on a fresh form. The imperative API lets a submit handler
+force every "sleeping" field's validator to run, rendering inline errors all
+at once — no synthetic `change` events, no DOM lookups, no id-format coupling.
+
+### The `validate` prop — defaults & opt-out
+
+All field components that use the `validate` action treat the prop with one
+consistent rule:
+
+| `validate` value          | Action                                                     |
+| ------------------------- | ---------------------------------------------------------- |
+| (omitted) / `undefined`   | **Enabled** with default options (the common case)         |
+| `true`                    | Enabled with default options (explicit; same as omitting)  |
+| `false`                   | **Disabled** — no validation, `validate()` becomes a no-op |
+| `{ customValidator, ... }`| Enabled, with `ValidateOptions` overrides applied          |
+
+So `<FieldInput required />` works as expected — required is enforced, and a
+failed `validate()` (imperative or event-driven) renders the inline error.
+Use `validate={false}` to bypass stuic's validation entirely.
+
+> **Why default-on?** Hidden-input field components (`FieldPhoneNumber`,
+> `FieldCountry`, `FieldObject`, `FieldAssets`, `FieldInputLocalized`,
+> `FieldKeyValues`, `FieldLikeButton`) *must* be default-on because hidden
+> inputs are excluded from native browser constraint validation — without the
+> stuic action enforcing `required` in a `customValidator`, the attribute is a
+> silent no-op. Plain-input field components were harmonized to the same
+> default to keep the rule uniform: "`required` means required."
+
+### Per-field methods
+
+Available on `FieldInput`, `FieldTextarea`, `FieldCheckbox`, `FieldSelect`,
+`FieldFile`, `FieldObject`, `FieldAssets`, `FieldInputLocalized`,
+`FieldKeyValues`, `FieldPhoneNumber`, `FieldCountry`, `FieldLikeButton`,
+`FieldRadios`, `FieldSwitch`, `FieldOptions`, and `Switch`:
+
+| Method                                        | Returns                          | Purpose                                                            |
+| --------------------------------------------- | -------------------------------- | ------------------------------------------------------------------ |
+| `validate()`                                  | `ValidationResult \| undefined`  | Run the validator now. Renders the inline message if invalid.       |
+| `clearValidation()`                           | `void`                           | Clear the inline message and `setCustomValidity`.                   |
+| `getValidation()`                             | `ValidationResult \| undefined`  | Read cached state (no re-run).                                      |
+| `focus()`                                     | `void`                           | Focus the visible interactive element.                              |
+| `scrollIntoView(opts?)`                       | `void`                           | Scroll the field into view. Defaults to `smooth` + `center`.        |
+
+```svelte
+<script>
+	let nameField = $state<FieldInput>();
+
+	function checkName() {
+		const result = nameField?.validate();
+		if (result && !result.valid) {
+			console.warn("Name invalid:", result.message);
+		}
+	}
+</script>
+
+<FieldInput bind:this={nameField} bind:value={name} label="Name" required />
+<Button onclick={checkName}>Check now</Button>
+```
+
+### Form-level methods
+
+`LoginForm`, `RegisterForm`, `LoginOrRegisterForm`, and `EmailVerifyForm` each
+expose:
+
+| Method                              | Returns   | Purpose                                                              |
+| ----------------------------------- | --------- | -------------------------------------------------------------------- |
+| `validate()`                        | `boolean` | Run every inner field's validator. `true` if all valid.              |
+| `scrollToFirstError(opts?)`         | `boolean` | Scroll the first invalid field into view + focus it. Call after `validate()`. |
+
+```svelte
+<script>
+	let loginForm = $state<LoginForm>();
+
+	async function handleCustomSubmit() {
+		if (!loginForm?.validate()) {
+			loginForm?.scrollToFirstError();
+			return;
+		}
+		await api.login(/* ... */);
+	}
+</script>
+
+<LoginForm bind:this={loginForm} onSubmit={handleCustomSubmit} />
+<Button onclick={handleCustomSubmit}>Submit from outside</Button>
+```
+
+### Pristine-form errors pattern
+
+The trap: an external `errors` prop wired into each field's `customValidator`
+won't render until the user touches the field. Pair the existing prop with
+an imperative `validate()` call from your submit handler:
+
+```svelte
+<FieldInput
+	bind:this={nameField}
+	bind:value={address.name}
+	required
+	validate={{
+		customValidator() {
+			return externalErrors.find((e) => e.field === "name")?.message || "";
+		},
+	}}
+/>
+
+<!-- in your submit handler -->
+<script>
+	function handleContinue() {
+		if (!validateAllFields([nameField, /* ... */])) return;
+		// ...submit
+	}
+</script>
+```
+
+For aggregation across many fields, see
+[validate-fields utilities](./utils.md#field-validation-aggregators).
+
+---
+
 ## LoginForm
 
 Standalone login form with optional modal variant. Supports social logins, forgot password, remember me, client+server validation, i18n, and notifications integration.

package/docs/domains/utils.md

@@ -173,6 +173,43 @@ storage.get("user"); // { name: 'John' }
 | `generateCssTokens`  | Convert token schema to CSS  |
 | `toCssString`        | Format tokens as CSS string  |
 
+---
+
+## Field Validation Aggregators
+
+Helpers for orchestrating `validate()` across multiple `Field*` components.
+Pair with the per-field imperative API documented in the
+[Components domain](./components.md#imperative-validate-api).
+
+| Util                          | Purpose                                                      |
+| ----------------------------- | ------------------------------------------------------------ |
+| `validateAllFields`           | Run `validate()` on every provided field ref. Returns `true` if all valid. |
+| `findFirstInvalidField`       | Return the first ref whose cached `getValidation()` is invalid. |
+| `scrollToFirstInvalidField`   | Scroll the first invalid field into view + focus (call after `validateAllFields`). |
+| `ValidatableField` (interface)| Minimal shape every STUIC `Field*` satisfies — your own components can too. |
+
+```ts
+import {
+	scrollToFirstInvalidField,
+	validateAllFields,
+} from "@marianmeres/stuic";
+
+let nameField = $state<FieldInput>();
+let emailField = $state<FieldInput>();
+let countryField = $state<FieldCountry>();
+
+function handleContinue() {
+	const allValid = validateAllFields([nameField, emailField, countryField]);
+	if (!allValid) {
+		scrollToFirstInvalidField([nameField, emailField, countryField]);
+		return;
+	}
+	// ...submit
+}
+```
+
+`undefined` / `null` entries are skipped so callers can spread conditional refs
+without filtering first.
 
 ---
 
@@ -184,4 +221,5 @@ storage.get("user"); // { name: 'John' }
 | src/lib/utils/tw-merge.ts                | Critical for class merging                |
 | src/lib/utils/persistent-state.svelte.ts | Reactive storage pattern (runes-based)    |
 | src/lib/utils/storage-abstraction.ts     | Non-reactive storage (localStorage, etc.) |
+| src/lib/utils/validate-fields.ts         | Form-level validation aggregators         |
 | src/lib/utils/design-tokens.ts           | Re-exports from `@marianmeres/design-tokens` |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.85.0",
+	"version": "3.87.0",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && pnpm run prepack",