@marianmeres/stuic 3.142.0 → 3.143.0

package/dist/components/Checkout/CheckoutAddressForm.svelte

@@ -5,8 +5,10 @@
 	import type { TranslateFn } from "../../types.js";
 	import type { Props as FieldCountryProps } from "../Input/FieldCountry.svelte";
 	import type { Props as FieldPhoneNumberProps } from "../Input/FieldPhoneNumber.svelte";
+	import type { Props as FieldSelectProps } from "../Input/FieldSelect.svelte";
 	import type {
 		CheckoutAddressData,
+		CheckoutSubdivisionOption,
 		CheckoutValidationError,
 	} from "./_internal/checkout-types.js";
 
@@ -87,6 +89,71 @@
 		 */
 		countryNames?: Record<string, string>;
 
+		/**
+		 * Subdivision (state/province/region) lists keyed by UPPERCASE ISO alpha-2
+		 * country code. When the currently selected `address.country` has a
+		 * non-empty entry, the `state_or_region` field renders as a fixed select
+		 * over these options (storing the option `code`); for every other country
+		 * it stays the default free-text input, whose value is never touched.
+		 * stuic ships no subdivision data — pass exactly the countries your
+		 * checkout logic keys on (tax, shipping). Default: undefined (free text
+		 * everywhere, current behavior).
+		 *
+		 * When the built-in select is active, a stored value is reconciled
+		 * against the list: an exact `code` match (case-insensitive) is
+		 * normalized to the canonical code, an exact `name` match ("Michigan")
+		 * is rewritten to its `code` ("MI"), and anything else is left
+		 * untouched and renders as unselected — surfaced by required-validation
+		 * rather than destroyed. Reconciliation is skipped when the `stateField`
+		 * snippet replaces the field — a custom control owns its value.
+		 *
+		 * Country edits made through this form flip the mode live even for a
+		 * plain (non-`$state`) `address` object; external mutations of a plain
+		 * object are not observable — pass a `$state` object for those.
+		 */
+		subdivisions?: Record<string, CheckoutSubdivisionOption[]>;
+
+		/**
+		 * Whether `state_or_region` is required while the subdivision select is
+		 * active (i.e. the current country has a `subdivisions` entry). Also
+		 * accepts a per-country predicate receiving the UPPERCASE ISO code.
+		 * Countries without a list keep the plain `requiredFields` behavior
+		 * (as does a `requiredFields` entry for "state_or_region", which wins
+		 * regardless). Default: true.
+		 */
+		subdivisionRequired?: boolean | ((countryIso: string) => boolean);
+
+		/**
+		 * Override the state/region field with a custom control (parity with
+		 * `countryField`). When provided, replaces the built-in field in both
+		 * modes; `options` is the active country's subdivision list, or null
+		 * when the free-text input would apply.
+		 */
+		stateField?: Snippet<
+			[
+				{
+					/** Current state/region value */
+					value: string;
+					/** Called when the value changes */
+					onchange: (value: string) => void;
+					/** Error message for this field (if any) */
+					error?: string;
+					/** Field label text */
+					label: string;
+					/** HTML id attribute for the input */
+					id: string;
+					/** Active country's subdivision list, or null (free-text mode) */
+					options: CheckoutSubdivisionOption[] | null;
+				},
+			]
+		>;
+
+		/**
+		 * Extra props forwarded to the internal FieldSelect when the subdivision
+		 * select is active (parity with `countryFieldProps`).
+		 */
+		stateFieldProps?: Partial<FieldSelectProps>;
+
 		/** Extra props forwarded to the internal FieldPhoneNumber component. */
 		phoneFieldProps?: Partial<FieldPhoneNumberProps>;
 
@@ -109,6 +176,7 @@
 	import FieldCountry from "../Input/FieldCountry.svelte";
 	import FieldInput from "../Input/FieldInput.svelte";
 	import FieldPhoneNumber from "../Input/FieldPhoneNumber.svelte";
+	import FieldSelect from "../Input/FieldSelect.svelte";
 	import { validatePhoneNumber } from "../Input/phone-validation.js";
 	import { t_default } from "./_internal/checkout-i18n-defaults.js";
 	import { createEmptyAddress } from "./_internal/checkout-utils.js";
@@ -125,6 +193,10 @@
 		countryList,
 		preferredCountries,
 		countryNames,
+		subdivisions,
+		subdivisionRequired = true,
+		stateField,
+		stateFieldProps,
 		phoneFieldProps,
 		countryFieldProps,
 		t: tProp,
@@ -147,6 +219,56 @@
 	let containerWidth = $state(0);
 	let isSmall = $derived(containerWidth > 0 && containerWidth < 480);
 
+	// Subdivision select mode (see the `subdivisions` prop) --------------------
+	// Local mirror of `address.country` (writable derived). The select/input
+	// mode must react to country edits even when the consumer passed a plain
+	// (non-$state) address object, whose deep mutations Svelte cannot observe —
+	// so every country write that goes through this form also overrides the
+	// mirror directly, while reactive addresses and prop replacement resync it
+	// through the derived expression. External mutations of a plain object stay
+	// unobservable (true for every field).
+	let _country = $derived(address.country ?? "");
+
+	function setCountry(v: string) {
+		address.country = v;
+		_country = v;
+	}
+
+	let _countryCC = $derived(_country.trim().toUpperCase());
+
+	let _subdivisionList = $derived.by(() => {
+		const list = _countryCC ? subdivisions?.[_countryCC] : undefined;
+		return list?.length ? list : null;
+	});
+
+	let _subdivisionIsRequired = $derived(
+		isRequired("state_or_region") ||
+			(typeof subdivisionRequired === "function"
+				? subdivisionRequired(_countryCC)
+				: subdivisionRequired)
+	);
+
+	// Reconcile a pre-existing value whenever the built-in select becomes
+	// active: legacy free-text rows ("Michigan", "mi") self-heal to the
+	// canonical code ("MI"); anything unrecognized is left untouched (renders
+	// unselected, caught by required-validation) — never destroyed. Converges:
+	// the write triggers one re-run which then matches the code branch with
+	// nothing to change. Skipped entirely under the `stateField` snippet — a
+	// custom control owns its value (a controlled combobox writing in-progress
+	// text through `onchange` must not have it rewritten mid-typing).
+	$effect(() => {
+		if (stateField) return;
+		const list = _subdivisionList;
+		if (!list) return;
+		const raw = address.state_or_region ?? "";
+		const needle = raw.trim().toLowerCase();
+		if (!needle) return;
+		const hit =
+			list.find((o) => o.code.toLowerCase() === needle) ??
+			list.find((o) => o.name.trim().toLowerCase() === needle);
+		if (hit && raw !== hit.code) address.state_or_region = hit.code;
+	});
+
 	let _class = $derived(
 		unstyled ? classProp : twMerge("stuic-checkout-address", classProp)
 	);
@@ -154,12 +276,12 @@
 	// 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.
+	// fields hidden via the `fields` prop or replaced by the `countryField`/
+	// `stateField` snippets — `validateAllFields` skips nullish entries.
 	let nameField = $state<FieldInput>();
 	let streetField = $state<FieldInput>();
 	let cityField = $state<FieldInput>();
-	let stateField = $state<FieldInput>();
+	let stateFieldRef = $state<FieldInput | FieldSelect>();
 	let postalCodeField = $state<FieldInput>();
 	let countryFieldRef = $state<FieldCountry>();
 	let phoneField = $state<FieldPhoneNumber>();
@@ -170,7 +292,7 @@
 			nameField,
 			streetField,
 			cityField,
-			stateField,
+			stateFieldRef,
 			postalCodeField,
 			countryFieldRef,
 			phoneField,
@@ -276,22 +398,63 @@
 				/>
 			{/if}
 			{#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}
-					placeholder={t("checkout.address.state_or_region_placeholder")}
-					required={isRequired("state_or_region")}
-					name="{label}-state_or_region"
-					id="{label}-state_or_region"
-					validate={{
-						customValidator(val) {
-							return fieldError("state_or_region") || "";
+				{#if stateField}
+					{@render stateField({
+						value: address.state_or_region ?? "",
+						onchange: (v) => {
+							address.state_or_region = v;
 						},
-					}}
-				/>
+						error: fieldError("state_or_region"),
+						label: t("checkout.address.state_or_region_label"),
+						id: `${label}-state_or_region`,
+						options: _subdivisionList,
+					})}
+				{:else if _subdivisionList}
+					<FieldSelect
+						bind:this={stateFieldRef}
+						bind:value={
+							() => address.state_or_region ?? "",
+							(v) => {
+								address.state_or_region = String(v ?? "");
+							}
+						}
+						options={[
+							{
+								label: t("checkout.address.state_or_region_select_placeholder"),
+								value: "",
+							},
+							..._subdivisionList.map((o) => ({ label: o.name, value: o.code })),
+						]}
+						label={t("checkout.address.state_or_region_label")}
+						labelLeftBreakpoint={0}
+						required={_subdivisionIsRequired}
+						name="{label}-state_or_region"
+						id="{label}-state_or_region"
+						validate={{
+							customValidator(val) {
+								return fieldError("state_or_region") || "";
+							},
+						}}
+						{...stateFieldProps}
+					/>
+				{:else}
+					<!-- svelte-ignore binding_property_non_reactive -->
+					<FieldInput
+						bind:this={stateFieldRef}
+						bind:value={address.state_or_region}
+						label={t("checkout.address.state_or_region_label")}
+						labelLeftBreakpoint={0}
+						placeholder={t("checkout.address.state_or_region_placeholder")}
+						required={isRequired("state_or_region")}
+						name="{label}-state_or_region"
+						id="{label}-state_or_region"
+						validate={{
+							customValidator(val) {
+								return fieldError("state_or_region") || "";
+							},
+						}}
+					/>
+				{/if}
 			{/if}
 			{#if fields?.postal_code !== false}
 				<!-- svelte-ignore binding_property_non_reactive -->
@@ -318,19 +481,16 @@
 	{#if fields?.country !== false}
 		{#if countryField}
 			{@render countryField({
-				value: address.country,
-				onchange: (v) => {
-					address.country = v;
-				},
+				value: _country,
+				onchange: setCountry,
 				error: fieldError("country"),
 				label: t("checkout.address.country_label"),
 				id: `${label}-country`,
 			})}
 		{:else}
-			<!-- svelte-ignore binding_property_non_reactive -->
 			<FieldCountry
 				bind:this={countryFieldRef}
-				bind:value={address.country}
+				bind:value={() => _country, setCountry}
 				label={t("checkout.address.country_label")}
 				placeholder={t("checkout.address.country_placeholder")}
 				required={isRequired("country")}

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

@@ -4,7 +4,8 @@ import type { HTMLAttributes } from "svelte/elements";
 import type { TranslateFn } from "../../types.js";
 import type { Props as FieldCountryProps } from "../Input/FieldCountry.svelte";
 import type { Props as FieldPhoneNumberProps } from "../Input/FieldPhoneNumber.svelte";
-import type { CheckoutAddressData, CheckoutValidationError } from "./_internal/checkout-types.js";
+import type { Props as FieldSelectProps } from "../Input/FieldSelect.svelte";
+import type { CheckoutAddressData, CheckoutSubdivisionOption, CheckoutValidationError } from "./_internal/checkout-types.js";
 export interface Props extends Omit<HTMLAttributes<HTMLFieldSetElement>, "children"> {
     /**
      * Bindable address data. Default: createEmptyAddress().
@@ -71,6 +72,65 @@ export interface Props extends Omit<HTMLAttributes<HTMLFieldSetElement>, "childr
      * values are the localized name. Missing keys fall back to English.
      */
     countryNames?: Record<string, string>;
+    /**
+     * Subdivision (state/province/region) lists keyed by UPPERCASE ISO alpha-2
+     * country code. When the currently selected `address.country` has a
+     * non-empty entry, the `state_or_region` field renders as a fixed select
+     * over these options (storing the option `code`); for every other country
+     * it stays the default free-text input, whose value is never touched.
+     * stuic ships no subdivision data — pass exactly the countries your
+     * checkout logic keys on (tax, shipping). Default: undefined (free text
+     * everywhere, current behavior).
+     *
+     * When the built-in select is active, a stored value is reconciled
+     * against the list: an exact `code` match (case-insensitive) is
+     * normalized to the canonical code, an exact `name` match ("Michigan")
+     * is rewritten to its `code` ("MI"), and anything else is left
+     * untouched and renders as unselected — surfaced by required-validation
+     * rather than destroyed. Reconciliation is skipped when the `stateField`
+     * snippet replaces the field — a custom control owns its value.
+     *
+     * Country edits made through this form flip the mode live even for a
+     * plain (non-`$state`) `address` object; external mutations of a plain
+     * object are not observable — pass a `$state` object for those.
+     */
+    subdivisions?: Record<string, CheckoutSubdivisionOption[]>;
+    /**
+     * Whether `state_or_region` is required while the subdivision select is
+     * active (i.e. the current country has a `subdivisions` entry). Also
+     * accepts a per-country predicate receiving the UPPERCASE ISO code.
+     * Countries without a list keep the plain `requiredFields` behavior
+     * (as does a `requiredFields` entry for "state_or_region", which wins
+     * regardless). Default: true.
+     */
+    subdivisionRequired?: boolean | ((countryIso: string) => boolean);
+    /**
+     * Override the state/region field with a custom control (parity with
+     * `countryField`). When provided, replaces the built-in field in both
+     * modes; `options` is the active country's subdivision list, or null
+     * when the free-text input would apply.
+     */
+    stateField?: Snippet<[
+        {
+            /** Current state/region value */
+            value: string;
+            /** Called when the value changes */
+            onchange: (value: string) => void;
+            /** Error message for this field (if any) */
+            error?: string;
+            /** Field label text */
+            label: string;
+            /** HTML id attribute for the input */
+            id: string;
+            /** Active country's subdivision list, or null (free-text mode) */
+            options: CheckoutSubdivisionOption[] | null;
+        }
+    ]>;
+    /**
+     * Extra props forwarded to the internal FieldSelect when the subdivision
+     * select is active (parity with `countryFieldProps`).
+     */
+    stateFieldProps?: Partial<FieldSelectProps>;
     /** Extra props forwarded to the internal FieldPhoneNumber component. */
     phoneFieldProps?: Partial<FieldPhoneNumberProps>;
     /** Extra props forwarded to the internal FieldCountry component. */

package/dist/components/Checkout/CheckoutShippingStep.svelte

@@ -99,6 +99,7 @@
 		 * Props forwarded to both inner `CheckoutAddressForm` instances (shipping
 		 * and, when visible, billing). Use this to configure `phoneFieldProps`,
 		 * `countryFieldProps`, `preferredCountries`, `countryList`, `countryNames`,
+		 * `subdivisions`, `subdivisionRequired`, `stateFieldProps`,
 		 * `requiredFields`, or `fields` without replacing the entire left column
 		 * via the `leftColumn` snippet.
 		 *

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

@@ -55,6 +55,7 @@ export interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "children">
      * Props forwarded to both inner `CheckoutAddressForm` instances (shipping
      * and, when visible, billing). Use this to configure `phoneFieldProps`,
      * `countryFieldProps`, `preferredCountries`, `countryList`, `countryNames`,
+     * `subdivisions`, `subdivisionRequired`, `stateFieldProps`,
      * `requiredFields`, or `fields` without replacing the entire left column
      * via the `leftColumn` snippet.
      *

package/dist/components/Checkout/README.md

@@ -126,6 +126,57 @@ interface CheckoutValidationError {
 
 The step component **does not auto-advance**. It calls `onContinue` when the user clicks "Continue"; the consumer decides whether to actually advance, retry, or show errors.
 
+## Country-aware state/region select (`subdivisions`)
+
+By default `CheckoutAddressForm` renders `state_or_region` as free text. For
+countries where downstream logic keys on an exact subdivision code (US
+sales-tax tables, shipping zones), pass `subdivisions` — lists keyed by
+UPPERCASE ISO alpha-2 country code. When the selected country has an entry,
+the field swaps to a fixed select storing the canonical `code`; every other
+country keeps the free-text input, verbatim. stuic ships **no** subdivision
+data — pass exactly what your app needs:
+
+```svelte
+<CheckoutAddressForm
+	bind:address
+	subdivisions={{
+		US: [
+			{ code: "AL", name: "Alabama" },
+			{ code: "AK", name: "Alaska" },
+			// ... full USPS list
+		],
+	}}
+/>
+```
+
+Behavior details:
+
+- **Stored value is always the `code`** ("MI") — same wire shape as free text,
+  no server contract change.
+- **Prefill reconciliation:** entering select mode with a legacy value
+  self-heals it — `"mi"` → `"MI"`, `"Michigan"` → `"MI"` (written back into
+  the bound `address`). Unrecognized values are left untouched and render as
+  unselected, surfaced by validation rather than destroyed. Applies only to
+  the built-in select — the `stateField` snippet owns its value entirely.
+- **Country switching never clears the field** — a US → CA → US round-trip
+  restores "MI".
+- **Required:** while the select is active the field is required by default
+  (`subdivisionRequired`, also accepts a per-country predicate
+  `(countryIso) => boolean`). Countries without a list keep the plain
+  `requiredFields` behavior.
+- `stateFieldProps` forwards extras to the internal `FieldSelect`; the
+  `stateField` snippet replaces the field entirely (receives the active
+  `options`, or `null` in free-text mode) — parity with
+  `countryField`/`countryFieldProps`.
+- i18n: the select's empty option uses
+  `checkout.address.state_or_region_select_placeholder` (default `"Select…"`).
+- Forward through composite steps via
+  `CheckoutShippingStep.addressFormProps`.
+
+Note: the `validateAddress()` utility has no access to the `subdivisions`
+config, so it does not enforce subdivision-required — use the component's
+imperative `validate()` (step containers already do).
+
 ## Price arithmetic
 
 **All monetary values are integers in the smallest currency unit (cents).** This applies to `CheckoutOrderLineItem.price`, `CheckoutDeliveryOption.price`, `CheckoutDeliveryOption.free_above`, and every field in `CheckoutOrderTotals`.

package/dist/components/Checkout/_internal/checkout-i18n-defaults.js

@@ -67,6 +67,7 @@ const DEFAULTS = {
     "checkout.address.city_placeholder": "",
     "checkout.address.state_or_region_label": "State / Region",
     "checkout.address.state_or_region_placeholder": "",
+    "checkout.address.state_or_region_select_placeholder": "Select…",
     "checkout.address.postal_code_label": "Postal Code",
     "checkout.address.postal_code_placeholder": "",
     "checkout.address.country_label": "Country",

package/dist/components/Checkout/_internal/checkout-types.d.ts

@@ -10,6 +10,17 @@ export interface CheckoutStep {
     /** Whether this step can be navigated to (clicked). Default: true for past steps */
     navigable?: boolean;
 }
+/**
+ * One selectable subdivision (state/province/region) for the
+ * `CheckoutAddressForm` `subdivisions` prop. stuic ships no subdivision
+ * data — consumers pass the lists for the countries they care about.
+ */
+export interface CheckoutSubdivisionOption {
+    /** Canonical stored value — ISO 3166-2 subdivision suffix / USPS code (e.g. "MI"). */
+    code: string;
+    /** Display name (e.g. "Michigan"). */
+    name: string;
+}
 export interface CheckoutAddressData {
     name: string;
     street: string;

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

@@ -12,5 +12,5 @@ export { default as CheckoutReviewStep, type Props as CheckoutReviewStepProps, }
 export { default as CheckoutShippingStep, type Props as CheckoutShippingStepProps, } from "./CheckoutShippingStep.svelte";
 export { default as CheckoutConfirmStep, type Props as CheckoutConfirmStepProps, } from "./CheckoutConfirmStep.svelte";
 export { default as CheckoutCompleteStep, type Props as CheckoutCompleteStepProps, } from "./CheckoutCompleteStep.svelte";
-export type { CheckoutStep, CheckoutAddressData, CheckoutCustomerFormData, CheckoutLoginFormData, CheckoutOrderLineItem, CheckoutOrderTotals, CheckoutDeliveryOption, CheckoutDeliverySnapshot, CheckoutOrderData, CheckoutValidationError, } from "./_internal/checkout-types.js";
+export type { CheckoutStep, CheckoutAddressData, CheckoutSubdivisionOption, CheckoutCustomerFormData, CheckoutLoginFormData, CheckoutOrderLineItem, CheckoutOrderTotals, CheckoutDeliveryOption, CheckoutDeliverySnapshot, CheckoutOrderData, CheckoutValidationError, } from "./_internal/checkout-types.js";
 export { defaultFormatPrice, validateEmail, validateAddress, validateCustomerForm, validateLoginForm, createEmptyAddress, createEmptyCustomerFormData, createEmptyLoginFormData, addressesEqual, } from "./_internal/checkout-utils.js";

package/dist/components/Input/FieldAssets.svelte

@@ -203,7 +203,10 @@
 		// routing would be ambiguous, so focus (a click on the field) must decide.
 		if (paste_targets.size === 1 && !is_text_entry(active)) {
 			const [t] = paste_targets;
-			if (is_visible(t.el) && (is_unclaimed_focus(active) || shares_modal(t.el, active))) {
+			if (
+				is_visible(t.el) &&
+				(is_unclaimed_focus(active) || shares_modal(t.el, active))
+			) {
 				t.handle(e);
 			}
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.142.0",
+	"version": "3.143.0",
 	"packageManager": "pnpm@11.5.0",
 	"scripts": {
 		"dev": "vite dev",