@marianmeres/stuic 3.88.0 → 3.89.0

package/dist/components/Checkout/CheckoutAddressForm.svelte

@@ -102,6 +102,10 @@
 
 <script lang="ts">
 	import { twMerge } from "../../utils/tw-merge.js";
+	import {
+		scrollToFirstInvalidField,
+		validateAllFields,
+	} from "../../utils/validate-fields.js";
 	import { t_default } from "./_internal/checkout-i18n-defaults.js";
 	import { createEmptyAddress } from "./_internal/checkout-utils.js";
 	import FieldInput from "../Input/FieldInput.svelte";
@@ -146,6 +150,56 @@
 	let _class = $derived(
 		unstyled ? classProp : twMerge("stuic-checkout-address", classProp)
 	);
+
+	// Imperative API ----------------------------------------------------------
+	// Field refs collected during render so consumers can trigger validation
+	// without waiting for native form submission. Refs stay undefined for
+	// fields hidden via the `fields` prop or replaced by the `countryField`
+	// snippet — `validateAllFields` skips nullish entries.
+	let nameField = $state<FieldInput>();
+	let streetField = $state<FieldInput>();
+	let cityField = $state<FieldInput>();
+	let stateField = $state<FieldInput>();
+	let postalCodeField = $state<FieldInput>();
+	let countryFieldRef = $state<FieldCountry>();
+	let phoneField = $state<FieldPhoneNumber>();
+
+	// DOM order top-to-bottom — first invalid wins for scrollToFirstError.
+	function _fields() {
+		return [
+			nameField,
+			streetField,
+			cityField,
+			stateField,
+			postalCodeField,
+			countryFieldRef,
+			phoneField,
+		];
+	}
+
+	/**
+	 * Run every visible field's validator and render any inline errors.
+	 * Returns true if all fields are valid. Pair with the `errors` prop:
+	 * set external errors first, await `tick()`, then call `validate()`.
+	 */
+	export function validate(): boolean {
+		return validateAllFields(_fields());
+	}
+
+	/**
+	 * Scroll the first invalid field into view and focus it. Returns true
+	 * if a field was scrolled. Call after `validate()`.
+	 */
+	export function scrollToFirstError(
+		opts?: Parameters<typeof scrollToFirstInvalidField>[1]
+	): boolean {
+		return scrollToFirstInvalidField(_fields(), opts);
+	}
+
+	/** Clear all inline validation messages on the rendered fields. */
+	export function clearValidation(): void {
+		for (const f of _fields()) f?.clearValidation?.();
+	}
 </script>
 
 <fieldset
@@ -164,6 +218,7 @@
 	{#if fields?.name !== false}
 		<!-- svelte-ignore binding_property_non_reactive -->
 		<FieldInput
+			bind:this={nameField}
 			bind:value={address.name}
 			label={t("checkout.address.name_label")}
 			placeholder={t("checkout.address.name_placeholder")}
@@ -183,6 +238,7 @@
 	{#if fields?.street !== false}
 		<!-- svelte-ignore binding_property_non_reactive -->
 		<FieldInput
+			bind:this={streetField}
 			bind:value={address.street}
 			label={t("checkout.address.street_label")}
 			placeholder={t("checkout.address.street_placeholder")}
@@ -204,6 +260,7 @@
 			{#if fields?.city !== false}
 				<!-- svelte-ignore binding_property_non_reactive -->
 				<FieldInput
+					bind:this={cityField}
 					bind:value={address.city}
 					label={t("checkout.address.city_label")}
 					labelLeftBreakpoint={0}
@@ -221,6 +278,7 @@
 			{#if fields?.state_or_region !== false}
 				<!-- svelte-ignore binding_property_non_reactive -->
 				<FieldInput
+					bind:this={stateField}
 					bind:value={address.state_or_region}
 					label={t("checkout.address.state_or_region_label")}
 					labelLeftBreakpoint={0}
@@ -238,6 +296,7 @@
 			{#if fields?.postal_code !== false}
 				<!-- svelte-ignore binding_property_non_reactive -->
 				<FieldInput
+					bind:this={postalCodeField}
 					bind:value={address.postal_code}
 					label={t("checkout.address.postal_code_label")}
 					labelLeftBreakpoint={0}
@@ -270,6 +329,7 @@
 		{:else}
 			<!-- svelte-ignore binding_property_non_reactive -->
 			<FieldCountry
+				bind:this={countryFieldRef}
 				bind:value={address.country}
 				label={t("checkout.address.country_label")}
 				placeholder={t("checkout.address.country_placeholder")}
@@ -294,6 +354,7 @@
 	<!-- Phone (full width, block label) -->
 	{#if fields?.phone !== false}
 		<FieldPhoneNumber
+			bind:this={phoneField}
 			value={address.phone ?? ""}
 			onChange={(v) => {
 				address.phone = v;

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

@@ -80,6 +80,11 @@ export interface Props extends Omit<HTMLAttributes<HTMLFieldSetElement>, "childr
     class?: string;
     el?: HTMLFieldSetElement;
 }
-declare const CheckoutAddressForm: import("svelte").Component<Props, {}, "el" | "address">;
+import { scrollToFirstInvalidField } from "../../utils/validate-fields.js";
+declare const CheckoutAddressForm: import("svelte").Component<Props, {
+    validate: () => boolean;
+    scrollToFirstError: (opts?: Parameters<typeof scrollToFirstInvalidField>[1]) => boolean;
+    clearValidation: () => void;
+}, "el" | "address">;
 type CheckoutAddressForm = ReturnType<typeof CheckoutAddressForm>;
 export default CheckoutAddressForm;

package/dist/components/Checkout/CheckoutGuestForm.svelte

@@ -71,6 +71,10 @@
 
 <script lang="ts">
 	import { twMerge } from "../../utils/tw-merge.js";
+	import {
+		scrollToFirstInvalidField,
+		validateAllFields,
+	} from "../../utils/validate-fields.js";
 	import { t_default } from "./_internal/checkout-i18n-defaults.js";
 	import {
 		createEmptyCustomerFormData,
@@ -139,6 +143,52 @@
 	let _class = $derived(
 		unstyled ? classProp : twMerge("stuic-checkout-guest-form", classProp)
 	);
+
+	// Imperative API ----------------------------------------------------------
+	// Field refs collected during render so consumers can trigger per-field
+	// inline messages without going through native form submission.
+	let emailField = $state<FieldInput>();
+	let firstNameField = $state<FieldInput>();
+	let lastNameField = $state<FieldInput>();
+	let phoneField = $state<FieldPhoneNumber>();
+	let companyNameField = $state<FieldInput>();
+	let taxIdField = $state<FieldInput>();
+	let vatNumberField = $state<FieldInput>();
+
+	function _fields() {
+		return [
+			emailField,
+			firstNameField,
+			lastNameField,
+			phoneField,
+			companyNameField,
+			taxIdField,
+			vatNumberField,
+		];
+	}
+
+	/**
+	 * Run every visible field's validator and render any inline errors.
+	 * Returns true if all fields are valid.
+	 */
+	export function validate(): boolean {
+		return validateAllFields(_fields());
+	}
+
+	/**
+	 * Scroll the first invalid field into view and focus it. Returns true
+	 * if a field was scrolled. Call after `validate()`.
+	 */
+	export function scrollToFirstError(
+		opts?: Parameters<typeof scrollToFirstInvalidField>[1]
+	): boolean {
+		return scrollToFirstInvalidField(_fields(), opts);
+	}
+
+	/** Clear all inline validation messages on the rendered fields. */
+	export function clearValidation(): void {
+		for (const f of _fields()) f?.clearValidation?.();
+	}
 </script>
 
 <form
@@ -158,6 +208,7 @@
 	<!-- Email (always shown, always required) -->
 	<!-- svelte-ignore binding_property_non_reactive -->
 	<FieldInput
+		bind:this={emailField}
 		bind:value={formData.email}
 		label={t("checkout.guest.email_label")}
 		type="email"
@@ -178,6 +229,7 @@
 			{#if fields?.first_name !== false}
 				<!-- svelte-ignore binding_property_non_reactive -->
 				<FieldInput
+					bind:this={firstNameField}
 					bind:value={formData.first_name}
 					label={t("checkout.guest.first_name_label")}
 					labelLeftBreakpoint={0}
@@ -188,6 +240,7 @@
 			{#if fields?.last_name !== false}
 				<!-- svelte-ignore binding_property_non_reactive -->
 				<FieldInput
+					bind:this={lastNameField}
 					bind:value={formData.last_name}
 					label={t("checkout.guest.last_name_label")}
 					labelLeftBreakpoint={0}
@@ -202,6 +255,7 @@
 	{#if fields?.phone !== false}
 		<!-- svelte-ignore binding_property_non_reactive -->
 		<FieldPhoneNumber
+			bind:this={phoneField}
 			bind:value={formData.phone}
 			label={t("checkout.guest.phone_label")}
 			placeholder={t("checkout.guest.phone_placeholder")}
@@ -221,6 +275,7 @@
 				{#if fields?.company_name !== false}
 					<!-- svelte-ignore binding_property_non_reactive -->
 					<FieldInput
+						bind:this={companyNameField}
 						bind:value={formData.company_name}
 						label={t("checkout.guest.company_name_label")}
 						name="checkout-guest-company-name"
@@ -232,6 +287,7 @@
 						{#if fields?.tax_id !== false}
 							<!-- svelte-ignore binding_property_non_reactive -->
 							<FieldInput
+								bind:this={taxIdField}
 								bind:value={formData.tax_id}
 								label={t("checkout.guest.tax_id_label")}
 								name="checkout-guest-tax-id"
@@ -240,6 +296,7 @@
 						{#if fields?.vat_number !== false}
 							<!-- svelte-ignore binding_property_non_reactive -->
 							<FieldInput
+								bind:this={vatNumberField}
 								bind:value={formData.vat_number}
 								label={t("checkout.guest.vat_number_label")}
 								name="checkout-guest-vat-number"

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

@@ -52,6 +52,11 @@ export interface Props extends Omit<HTMLAttributes<HTMLFormElement>, "children">
     class?: string;
     el?: HTMLFormElement;
 }
-declare const CheckoutGuestForm: import("svelte").Component<Props, {}, "el" | "formData">;
+import { scrollToFirstInvalidField } from "../../utils/validate-fields.js";
+declare const CheckoutGuestForm: import("svelte").Component<Props, {
+    validate: () => boolean;
+    scrollToFirstError: (opts?: Parameters<typeof scrollToFirstInvalidField>[1]) => boolean;
+    clearValidation: () => void;
+}, "el" | "formData">;
 type CheckoutGuestForm = ReturnType<typeof CheckoutGuestForm>;
 export default CheckoutGuestForm;

package/dist/components/Checkout/CheckoutGuestOrLoginForm.svelte

@@ -114,6 +114,7 @@
 
 <script lang="ts">
 	import { twMerge } from "../../utils/tw-merge.js";
+	import type { scrollToFirstInvalidField } from "../../utils/validate-fields.js";
 	import { t_default } from "./_internal/checkout-i18n-defaults.js";
 	import CheckoutGuestForm from "./CheckoutGuestForm.svelte";
 	import CheckoutLoginForm from "./CheckoutLoginForm.svelte";
@@ -262,6 +263,44 @@
 	let _class = $derived(
 		unstyled ? classProp : twMerge("stuic-checkout-guest-or-login-form", classProp)
 	);
+
+	// Imperative API ----------------------------------------------------------
+	// Routes to whichever inner form is currently visible inline. Modal-based
+	// flows (loginModal, loginOrRegisterModal) own their own submit/validate
+	// flow and are not validated through here.
+	let guestFormRef = $state<CheckoutGuestForm>();
+	let loginFormRef = $state<CheckoutLoginForm>();
+
+	function _activeForm(): CheckoutGuestForm | CheckoutLoginForm | undefined {
+		if (formMode === "guest-only") return guestFormRef;
+		if (formMode === "login-only") return loginFormRef;
+		if (formMode === "stacked") {
+			return activeTab === "login" ? loginFormRef : guestFormRef;
+		}
+		// "tabbed"
+		if (activeTab === "guest") return guestFormRef;
+		// login tab — falls through to modal when configured; no inline form
+		if (_useLoginModal || _useLoginOrRegisterModal) return undefined;
+		return loginFormRef;
+	}
+
+	/** Run validation on the currently active inline form. */
+	export function validate(): boolean {
+		return _activeForm()?.validate() ?? true;
+	}
+
+	/** Scroll the first invalid field on the active inline form into view. */
+	export function scrollToFirstError(
+		opts?: Parameters<typeof scrollToFirstInvalidField>[1]
+	): boolean {
+		return _activeForm()?.scrollToFirstError(opts) ?? false;
+	}
+
+	/** Clear all inline validation messages on both inner forms. */
+	export function clearValidation(): void {
+		guestFormRef?.clearValidation();
+		loginFormRef?.clearValidation();
+	}
 </script>
 
 <div bind:this={el} class={_class} {...rest}>
@@ -280,11 +319,23 @@
 
 	{#if formMode === "guest-only"}
 		{#if guestForm}
-			<CheckoutGuestForm {...guestForm} {notifications} t={tProp} {unstyled} />
+			<CheckoutGuestForm
+				bind:this={guestFormRef}
+				{...guestForm}
+				{notifications}
+				t={tProp}
+				{unstyled}
+			/>
 		{/if}
 	{:else if formMode === "login-only"}
 		{#if loginForm}
-			<CheckoutLoginForm {...loginForm} {notifications} t={tProp} {unstyled} />
+			<CheckoutLoginForm
+				bind:this={loginFormRef}
+				{...loginForm}
+				{notifications}
+				t={tProp}
+				{unstyled}
+			/>
 		{/if}
 	{:else if formMode === "tabbed"}
 		<ButtonGroupRadio
@@ -304,19 +355,43 @@
 			}}
 		/>
 		{#if activeTab === "guest" && guestForm}
-			<CheckoutGuestForm {...guestForm} {notifications} t={tProp} {unstyled} />
+			<CheckoutGuestForm
+				bind:this={guestFormRef}
+				{...guestForm}
+				{notifications}
+				t={tProp}
+				{unstyled}
+			/>
 		{:else if activeTab === "login" && loginForm && !_useLoginOrRegisterModal && !_useLoginModal}
-			<CheckoutLoginForm {...loginForm} {notifications} t={tProp} {unstyled} />
+			<CheckoutLoginForm
+				bind:this={loginFormRef}
+				{...loginForm}
+				{notifications}
+				t={tProp}
+				{unstyled}
+			/>
 		{/if}
 	{:else if formMode === "stacked"}
 		{#if loginForm}
-			<CheckoutLoginForm {...loginForm} {notifications} t={tProp} {unstyled} />
+			<CheckoutLoginForm
+				bind:this={loginFormRef}
+				{...loginForm}
+				{notifications}
+				t={tProp}
+				{unstyled}
+			/>
 		{/if}
 		<div class={unstyled ? undefined : "stuic-checkout-guest-or-login-divider"}>
 			<span>{t("checkout.step.or_divider")}</span>
 		</div>
 		{#if guestForm}
-			<CheckoutGuestForm {...guestForm} {notifications} t={tProp} {unstyled} />
+			<CheckoutGuestForm
+				bind:this={guestFormRef}
+				{...guestForm}
+				{notifications}
+				t={tProp}
+				{unstyled}
+			/>
 		{/if}
 	{/if}
 

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

@@ -57,7 +57,12 @@ export interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "children">
     hLevel?: HLevel;
     hRenderLevel?: HLevel;
 }
+import type { scrollToFirstInvalidField } from "../../utils/validate-fields.js";
 import { type HLevel } from "../H/index.js";
-declare const CheckoutGuestOrLoginForm: import("svelte").Component<Props, {}, "el" | "activeTab">;
+declare const CheckoutGuestOrLoginForm: import("svelte").Component<Props, {
+    validate: () => boolean;
+    scrollToFirstError: (opts?: Parameters<typeof scrollToFirstInvalidField>[1]) => boolean;
+    clearValidation: () => void;
+}, "el" | "activeTab">;
 type CheckoutGuestOrLoginForm = ReturnType<typeof CheckoutGuestOrLoginForm>;
 export default CheckoutGuestOrLoginForm;

package/dist/components/Checkout/CheckoutLoginForm.svelte

@@ -75,6 +75,7 @@
 
 <script lang="ts">
 	import { twMerge } from "../../utils/tw-merge.js";
+	import type { scrollToFirstInvalidField } from "../../utils/validate-fields.js";
 	import { t_default } from "./_internal/checkout-i18n-defaults.js";
 	import { createEmptyLoginFormData } from "./_internal/checkout-utils.js";
 	import LoginForm from "../LoginForm/LoginForm.svelte";
@@ -120,6 +121,40 @@
 	let _class = $derived(
 		unstyled ? classProp : twMerge("stuic-checkout-login-form", classProp)
 	);
+
+	// Imperative API ----------------------------------------------------------
+	// Thin delegation to the wrapped LoginForm's own imperative API.
+	let loginFormRef = $state<LoginForm>();
+
+	/** Run validation on the wrapped LoginForm. Returns true if valid. */
+	export function validate(): boolean {
+		return loginFormRef?.validate() ?? true;
+	}
+
+	/** Scroll the first invalid field into view. Call after `validate()`. */
+	export function scrollToFirstError(
+		opts?: Parameters<typeof scrollToFirstInvalidField>[1]
+	): boolean {
+		return loginFormRef?.scrollToFirstError(opts) ?? false;
+	}
+
+	/**
+	 * Clear all inline validation messages on the wrapped LoginForm.
+	 * Currently a no-op because LoginForm doesn't yet expose
+	 * clearValidation — present for API symmetry with the other Checkout
+	 * composites; will start working once LoginForm gains the method.
+	 */
+	export function clearValidation(): void {
+		// loginFormRef?.clearValidation?.();
+	}
 </script>
 
-<LoginForm bind:formData bind:el t={adaptedT} {unstyled} class={_class} {...rest} />
+<LoginForm
+	bind:this={loginFormRef}
+	bind:formData
+	bind:el
+	t={adaptedT}
+	{unstyled}
+	class={_class}
+	{...rest}
+/>

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

@@ -56,6 +56,11 @@ export interface Props extends Omit<HTMLAttributes<HTMLFormElement>, "children">
     class?: string;
     el?: HTMLFormElement;
 }
-declare const CheckoutLoginForm: import("svelte").Component<Props, {}, "el" | "formData">;
+import type { scrollToFirstInvalidField } from "../../utils/validate-fields.js";
+declare const CheckoutLoginForm: import("svelte").Component<Props, {
+    validate: () => boolean;
+    scrollToFirstError: (opts?: Parameters<typeof scrollToFirstInvalidField>[1]) => boolean;
+    clearValidation: () => void;
+}, "el" | "formData">;
 type CheckoutLoginForm = ReturnType<typeof CheckoutLoginForm>;
 export default CheckoutLoginForm;

package/dist/components/Checkout/CheckoutShippingStep.svelte

@@ -115,6 +115,7 @@
 
 <script lang="ts">
 	import { twMerge } from "../../utils/tw-merge.js";
+	import type { scrollToFirstInvalidField } from "../../utils/validate-fields.js";
 	import Button from "../Button/Button.svelte";
 	import FieldCheckbox from "../Input/FieldCheckbox.svelte";
 	import Skeleton from "../Skeleton/Skeleton.svelte";
@@ -173,6 +174,44 @@
 	let _class = $derived(
 		unstyled ? classProp : twMerge("stuic-checkout-shipping-step", classProp)
 	);
+
+	// Imperative API ----------------------------------------------------------
+	// Refs to the inner address forms so consumers can trigger validation
+	// across shipping + (conditionally) billing without binding to each form.
+	let shippingFormRef = $state<CheckoutAddressForm>();
+	let billingFormRef = $state<CheckoutAddressForm>();
+
+	/**
+	 * Run validation on the shipping form (and billing, if visible).
+	 * Returns true if everything is valid. Pair with the `*Errors` props:
+	 * set external errors first, await `tick()`, then call `validate()`.
+	 */
+	export function validate(): boolean {
+		const shippingValid = shippingFormRef?.validate() ?? true;
+		const billingValid = billingSameAsShipping
+			? true
+			: (billingFormRef?.validate() ?? true);
+		return shippingValid && billingValid;
+	}
+
+	/**
+	 * Scroll the first invalid field across both forms into view. Shipping
+	 * comes first in the DOM, so it gets priority.
+	 */
+	export function scrollToFirstError(
+		opts?: Parameters<typeof scrollToFirstInvalidField>[1]
+	): boolean {
+		if (shippingFormRef?.scrollToFirstError(opts)) return true;
+		if (!billingSameAsShipping && billingFormRef?.scrollToFirstError(opts))
+			return true;
+		return false;
+	}
+
+	/** Clear all inline validation messages on both address forms. */
+	export function clearValidation(): void {
+		shippingFormRef?.clearValidation();
+		billingFormRef?.clearValidation();
+	}
 </script>
 
 <div bind:this={el} class={_class} {...rest}>
@@ -227,6 +266,7 @@
 							</H>
 						</CheckoutSectionHeader>
 						<CheckoutAddressForm
+							bind:this={shippingFormRef}
 							bind:address={shippingAddress}
 							label="shipping"
 							errors={shippingErrors}
@@ -252,6 +292,7 @@
 								</H>
 							</CheckoutSectionHeader>
 							<CheckoutAddressForm
+								bind:this={billingFormRef}
 								bind:address={billingAddress}
 								label="billing"
 								errors={billingErrors}

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

@@ -63,7 +63,12 @@ export interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "children">
     hLevel?: HLevel;
     hRenderLevel?: HLevel;
 }
+import type { scrollToFirstInvalidField } from "../../utils/validate-fields.js";
 import { type HLevel } from "../H/H.svelte";
-declare const CheckoutShippingStep: import("svelte").Component<Props, {}, "el" | "shippingAddress" | "billingAddress" | "billingSameAsShipping" | "selectedDeliveryId">;
+declare const CheckoutShippingStep: import("svelte").Component<Props, {
+    validate: () => boolean;
+    scrollToFirstError: (opts?: Parameters<typeof scrollToFirstInvalidField>[1]) => boolean;
+    clearValidation: () => void;
+}, "el" | "shippingAddress" | "billingAddress" | "billingSameAsShipping" | "selectedDeliveryId">;
 type CheckoutShippingStep = ReturnType<typeof CheckoutShippingStep>;
 export default CheckoutShippingStep;

package/dist/components/LoginForm/LoginForm.svelte

@@ -247,7 +247,13 @@
 	}
 </script>
 
-<form bind:this={formEl} class={_class} use:onSubmitValidityCheck {...rest}>
+<form
+	bind:this={formEl}
+	class={_class}
+	use:onSubmitValidityCheck
+	novalidate
+	{...rest}
+>
 	<!-- General error alert -->
 	<DismissibleMessage message={error} intent="destructive" />
 

package/dist/components/RegisterForm/RegisterForm.svelte

@@ -257,7 +257,13 @@
 	}
 </script>
 
-<form bind:this={formEl} class={_class} use:onSubmitValidityCheck {...rest}>
+<form
+	bind:this={formEl}
+	class={_class}
+	use:onSubmitValidityCheck
+	novalidate
+	{...rest}
+>
 	<!-- General error alert -->
 	<DismissibleMessage message={error} intent="destructive" />
 

package/package.json

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