@alikhalilll/a-tel-input 1.0.2 → 1.1.1

package/dist/index.js

@@ -1,9 +1,9 @@
+import { i as normalizeDigits, n as usePhoneValidation, r as LOCALE_DIGIT_RANGES, t as localizeCountries } from "./_chunks/usePhoneValidation.js";
+import { i as resolveMessages, n as DEFAULT_MESSAGES, r as aTelInputVariants, t as DEFAULT_ERROR_MESSAGES } from "./_chunks/types.js";
 import * as vue from "vue";
 import { Comment, Fragment, Teleport, Transition, camelize, cloneVNode, computed, createBlock, createCommentVNode, createElementBlock, createElementVNode, createSlots, createVNode, defineComponent, getCurrentInstance, guardReactiveProps, h, inject, isRef, mergeDefaults, mergeModels, mergeProps, nextTick, normalizeClass, normalizeProps, normalizeStyle, onBeforeUnmount, onMounted, onUnmounted, onUpdated, openBlock, provide, reactive, readonly, ref, renderList, renderSlot, resolveDynamicComponent, toDisplayString, toHandlerKey, toRef, toRefs, toValue, triggerRef, unref, useId, useModel, useSlots, vModelText, watch, watchEffect, watchPostEffect, withCtx, withDirectives, withModifiers } from "vue";
-import { getExampleNumber, isValidPhoneNumber, parsePhoneNumberFromString } from "libphonenumber-js";
-import examples from "libphonenumber-js/examples.mobile.json";
+import { getCountries, parsePhoneNumberFromString } from "libphonenumber-js";
 import { computedEager, createGlobalState, createSharedComposable, defaultWindow, onKeyStroke, reactiveOmit, unrefElement, useDebounceFn, useEventListener, useMediaQuery, useMounted, useVModel } from "@vueuse/core";
-import { cva } from "class-variance-authority";
 import { hideOthers } from "aria-hidden";
 //#region ../../../node_modules/.pnpm/clsx@2.1.1/node_modules/clsx/dist/clsx.mjs
 function r$2(e) {
@@ -3404,508 +3404,6 @@ function cn$2(...inputs) {
 	return twMerge$2(clsx$2(inputs));
 }
 //#endregion
-//#region src/utils/digits.ts
-/**
-* Alternative-numeral support. Phone numbers are routinely entered with the digits of the
-* user's own script — Arabic-Indic, Persian/Urdu, Devanagari, Bengali. `libphonenumber-js`
-* and our own `\d` cleanup only understand ASCII `0-9`, so anything else silently becomes
-* an empty number. `normalizeDigits` folds those scripts down to ASCII before validation.
-*/
-/**
-* Base code points of contiguous decimal-digit blocks. Each block runs `base`‥`base+9`
-* for digit `0`‥`9`, so the ASCII digit is `codePoint - base`. Add a script by appending
-* one entry here.
-*/
-const LOCALE_DIGIT_RANGES = [
-	{
-		name: "arabic-indic",
-		base: 1632
-	},
-	{
-		name: "extended-arabic",
-		base: 1776
-	},
-	{
-		name: "devanagari",
-		base: 2406
-	},
-	{
-		name: "bengali",
-		base: 2534
-	}
-];
-/** Lookup of every non-ASCII digit code point → its ASCII character. */
-const DIGIT_MAP = (() => {
-	const map = /* @__PURE__ */ new Map();
-	for (const { base } of LOCALE_DIGIT_RANGES) for (let d = 0; d <= 9; d++) map.set(base + d, String(d));
-	return map;
-})();
-/**
-* Replace any supported non-ASCII decimal digit with its ASCII equivalent. Every other
-* character (spaces, `+`, separators, letters) is left untouched — callers still run their
-* own `\D` cleanup afterwards.
-*/
-function normalizeDigits(input) {
-	const str = String(input ?? "");
-	let out = "";
-	for (const ch of str) {
-		const cp = ch.codePointAt(0);
-		out += cp != null && DIGIT_MAP.get(cp) || ch;
-	}
-	return out;
-}
-//#endregion
-//#region src/composables/usePhoneValidation.ts
-/**
-* Country list + phone validation, framework-agnostic.
-*
-* Ported from the reference @pkgs/ui ATelInput composable with these cleanups:
-*  - Drop Nuxt-only `process.client` checks → use plain `typeof window !== 'undefined'`.
-*  - Drop Arabic default placeholder; let consumers pass their own.
-*  - Expand the offline fallback list from 2 → ~20 of the most-populated countries.
-*  - Keep REST Countries fetch + localStorage cache + libphonenumber-js examples + fast `search_key`.
-*/
-const STORAGE_KEY = "ali_ui_phone_countries_v1";
-const REST_COUNTRIES_URL = "https://restcountries.com/v3.1/all?fields=name,cca2,idd,flags";
-const EX = examples;
-const isBrowser$1 = () => typeof window !== "undefined";
-function toDigits(v) {
-	return normalizeDigits(String(v ?? "")).replace(/\D/g, "");
-}
-/**
-* Render an ASCII digit string in a locale's numeral system (e.g. `'ar'` → `٠-٩`).
-* Used only for display hints — falls back to ASCII if the locale is unknown.
-*/
-function localizeDigits(digits, locale) {
-	if (!locale) return digits;
-	try {
-		const fmt = new Intl.NumberFormat(locale, { useGrouping: false });
-		return digits.replace(/[0-9]/g, (d) => fmt.format(Number(d)));
-	} catch {
-		return digits;
-	}
-}
-function ensurePlusDial(dial) {
-	const d = toDigits(dial);
-	return d ? `+${d}` : "";
-}
-function normalizeIso2(iso2) {
-	return String(iso2 ?? "").trim().toUpperCase();
-}
-function dropLeadingZeros(digits) {
-	return String(digits ?? "").replace(/^0+/, "");
-}
-function buildFullE164(dial, digits) {
-	const dialClean = ensurePlusDial(dial);
-	const nsn = dropLeadingZeros(toDigits(digits));
-	return dialClean && nsn ? `${dialClean}${nsn}` : null;
-}
-function inferLengthFromExample(national) {
-	const d = toDigits(national);
-	if (!d) return {
-		min: null,
-		max: null
-	};
-	const n = d.length;
-	return {
-		min: Math.max(4, n - 2),
-		max: n + 2
-	};
-}
-function buildDialCode(idd) {
-	const root = idd?.root?.trim();
-	if (!root || !root.startsWith("+")) return null;
-	const out = `${root}${idd?.suffixes?.[0]?.trim() ?? ""}`;
-	return out.startsWith("+") ? out : null;
-}
-function normalizeSearchKey(input) {
-	return String(input ?? "").toLowerCase().replace(/\s+/g, " ").trim().replace(/[^\p{L}\p{N}+ ]/gu, "");
-}
-/**
-* Return a copy of the country list with display names localized to `locale` via
-* `Intl.DisplayNames`. `search_key` is rebuilt (keeping the English name too) so search
-* still matches either spelling. Unknown locales / regions fall back to the English name.
-*/
-function localizeCountries(list, locale) {
-	if (!locale) return list;
-	let display;
-	try {
-		display = new Intl.DisplayNames([locale], { type: "region" });
-	} catch {
-		return list;
-	}
-	return list.map((c) => {
-		let localized = c.raw_data.name;
-		try {
-			localized = display.of(c.raw_data.iso2) || c.raw_data.name;
-		} catch {}
-		if (localized === c.raw_data.name) return c;
-		const dial = c.raw_data.dial_code;
-		return {
-			...c,
-			label: `${localized} (${dial})`,
-			search_key: normalizeSearchKey(`${localized} ${c.raw_data.name} ${dial} ${c.raw_data.iso2} ${c.raw_data.dial_digits}`),
-			raw_data: {
-				...c.raw_data,
-				name: localized
-			}
-		};
-	});
-}
-function makeFallback(iso2, name, dial) {
-	const dialDigits = toDigits(dial);
-	return {
-		label: `${name} (+${dialDigits})`,
-		value: iso2,
-		search_key: normalizeSearchKey(`${name} +${dialDigits} ${iso2}`),
-		raw_data: {
-			iso2,
-			dial_code: `+${dialDigits}`,
-			dial_digits: dialDigits,
-			name,
-			flag: `https://flagcdn.com/w40/${iso2.toLowerCase()}.png`,
-			source: "fallback",
-			original: {}
-		}
-	};
-}
-const FALLBACK_COUNTRIES = [
-	makeFallback("SA", "Saudi Arabia", "+966"),
-	makeFallback("EG", "Egypt", "+20"),
-	makeFallback("AE", "United Arab Emirates", "+971"),
-	makeFallback("US", "United States", "+1"),
-	makeFallback("GB", "United Kingdom", "+44"),
-	makeFallback("DE", "Germany", "+49"),
-	makeFallback("FR", "France", "+33"),
-	makeFallback("ES", "Spain", "+34"),
-	makeFallback("IT", "Italy", "+39"),
-	makeFallback("TR", "Turkey", "+90"),
-	makeFallback("RU", "Russia", "+7"),
-	makeFallback("CN", "China", "+86"),
-	makeFallback("IN", "India", "+91"),
-	makeFallback("JP", "Japan", "+81"),
-	makeFallback("KR", "South Korea", "+82"),
-	makeFallback("BR", "Brazil", "+55"),
-	makeFallback("MX", "Mexico", "+52"),
-	makeFallback("CA", "Canada", "+1"),
-	makeFallback("AU", "Australia", "+61"),
-	makeFallback("NG", "Nigeria", "+234"),
-	makeFallback("PK", "Pakistan", "+92"),
-	makeFallback("ID", "Indonesia", "+62")
-];
-function usePhoneValidation() {
-	const countries = ref([]);
-	const isCountriesLoading = ref(false);
-	const byValue = ref(/* @__PURE__ */ new Map());
-	const byDialDigits = ref(/* @__PURE__ */ new Map());
-	function rebuildIndexes(list) {
-		const valueMap = /* @__PURE__ */ new Map();
-		const dialMap = /* @__PURE__ */ new Map();
-		for (const item of list) {
-			valueMap.set(item.value, item);
-			const dial = item.raw_data.dial_digits;
-			if (dial) {
-				const bucket = dialMap.get(dial) ?? [];
-				bucket.push(item);
-				dialMap.set(dial, bucket);
-			}
-		}
-		byValue.value = valueMap;
-		byDialDigits.value = dialMap;
-	}
-	function upsertCountries(list) {
-		countries.value = list;
-		rebuildIndexes(list);
-	}
-	function normalizeRestCountries(list) {
-		const out = [];
-		for (const c of list) {
-			const name = c?.name?.common?.trim();
-			const iso2 = normalizeIso2(c?.cca2);
-			const dial = buildDialCode(c?.idd);
-			const flag = c?.flags?.png?.trim() || c?.flags?.svg?.trim() || null;
-			if (!name || !iso2 || !dial) continue;
-			const dialDigits = toDigits(dial);
-			const search_key = normalizeSearchKey(`${name} ${dial} ${iso2} ${dialDigits}`);
-			out.push({
-				label: `${name} (${dial})`,
-				value: iso2,
-				search_key,
-				raw_data: {
-					iso2,
-					dial_code: dial,
-					dial_digits: dialDigits,
-					name,
-					flag,
-					source: "restcountries",
-					original: c
-				}
-			});
-		}
-		const map = /* @__PURE__ */ new Map();
-		for (const item of out) {
-			const prev = map.get(item.value);
-			if (!prev) {
-				map.set(item.value, item);
-				continue;
-			}
-			const prevScore = (prev.raw_data.flag ? 1 : 0) + (prev.raw_data.dial_code ? 1 : 0);
-			if ((item.raw_data.flag ? 1 : 0) + (item.raw_data.dial_code ? 1 : 0) > prevScore) map.set(item.value, item);
-		}
-		return Array.from(map.values()).sort((a, b) => a.raw_data.name.localeCompare(b.raw_data.name));
-	}
-	async function getCountries(options) {
-		const force = Boolean(options?.force);
-		if (!force && countries.value.length) return countries.value;
-		if (!force && isBrowser$1()) try {
-			const cached = localStorage.getItem(STORAGE_KEY);
-			if (cached) {
-				const parsed = JSON.parse(cached);
-				if (Array.isArray(parsed) && parsed.length) {
-					upsertCountries(parsed);
-					return countries.value;
-				}
-			}
-		} catch {}
-		isCountriesLoading.value = true;
-		try {
-			const res = await fetch(REST_COUNTRIES_URL);
-			if (!res.ok) throw new Error(`Failed to fetch countries: ${res.status}`);
-			const normalized = normalizeRestCountries(await res.json());
-			upsertCountries(normalized.length ? normalized : FALLBACK_COUNTRIES);
-			if (isBrowser$1()) try {
-				localStorage.setItem(STORAGE_KEY, JSON.stringify(countries.value));
-			} catch {}
-			return countries.value;
-		} catch {
-			upsertCountries(FALLBACK_COUNTRIES);
-			return countries.value;
-		} finally {
-			isCountriesLoading.value = false;
-		}
-	}
-	function searchCountries(keyword, limit = 50) {
-		const q = normalizeSearchKey(keyword);
-		if (!q) return countries.value.slice(0, limit);
-		const res = [];
-		for (const item of countries.value) if (item.search_key.includes(q)) {
-			res.push(item);
-			if (res.length >= limit) break;
-		}
-		return res;
-	}
-	function getCountryByValue(value) {
-		return byValue.value.get(normalizeIso2(value)) ?? null;
-	}
-	function getCountriesByDial(dial) {
-		return byDialDigits.value.get(toDigits(dial)) ?? [];
-	}
-	function getRequiredInfo(country, locale) {
-		const iso2 = normalizeIso2(country.iso2);
-		if (!iso2) return null;
-		try {
-			const example = getExampleNumber(iso2, EX);
-			const exampleNational = example?.formatNational?.() ?? "";
-			const exampleE164 = example?.format?.("E.164") ?? "";
-			const inferred = inferLengthFromExample(exampleNational);
-			const dial_code = country.dial_code ? ensurePlusDial(country.dial_code) : exampleE164 ? `+${example?.countryCallingCode}` : "";
-			const digitsExample = toDigits(exampleNational);
-			return {
-				iso2,
-				dial_code,
-				placeholder: "",
-				example_national: exampleNational,
-				example_e164: exampleE164,
-				national_number_length: inferred,
-				format_hint: digitsExample ? `e.g. ${localizeDigits(digitsExample, locale)}` : ""
-			};
-		} catch {
-			return null;
-		}
-	}
-	function validate(input) {
-		const country = input.country ?? null;
-		if (!country?.iso2) return {
-			ok: false,
-			reason: "missing_country",
-			country: null,
-			phone: {
-				raw: ("phone" in input ? input.phone : null) ?? null,
-				digits: ""
-			},
-			full_phone: null,
-			required: null
-		};
-		const iso2 = normalizeIso2(country.iso2);
-		const required = getRequiredInfo({
-			iso2,
-			dial_code: country.dial_code
-		}, input.locale);
-		if (!required) return {
-			ok: false,
-			reason: "country_not_supported",
-			country: {
-				iso2,
-				dial_code: ensurePlusDial(country.dial_code)
-			},
-			phone: {
-				raw: ("phone" in input ? input.phone : null) ?? null,
-				digits: ""
-			},
-			full_phone: null,
-			required: null
-		};
-		if (!("phone" in input)) return {
-			ok: true,
-			reason: null,
-			country: {
-				iso2: required.iso2,
-				dial_code: required.dial_code
-			},
-			phone: {
-				raw: null,
-				digits: ""
-			},
-			full_phone: null,
-			required
-		};
-		const raw = input.phone;
-		const digits = toDigits(raw);
-		if (!raw || !String(raw).trim()) return {
-			ok: true,
-			reason: null,
-			country: {
-				iso2: required.iso2,
-				dial_code: required.dial_code
-			},
-			phone: {
-				raw: raw ?? null,
-				digits: ""
-			},
-			full_phone: null,
-			required
-		};
-		if (String(raw).replace(/\s+/g, "").match(/[^\d+]/)) return {
-			ok: false,
-			reason: "phone_has_non_digits",
-			country: {
-				iso2: required.iso2,
-				dial_code: required.dial_code
-			},
-			phone: {
-				raw,
-				digits
-			},
-			full_phone: buildFullE164(required.dial_code, digits),
-			required
-		};
-		const nsn = dropLeadingZeros(digits);
-		const { min, max } = required.national_number_length;
-		if (min !== null && nsn.length < min) return {
-			ok: false,
-			reason: "too_short",
-			country: {
-				iso2: required.iso2,
-				dial_code: required.dial_code
-			},
-			phone: {
-				raw,
-				digits
-			},
-			full_phone: buildFullE164(required.dial_code, digits),
-			required,
-			details: {
-				min,
-				actual: nsn.length
-			}
-		};
-		if (max !== null && nsn.length > max) return {
-			ok: false,
-			reason: "too_long",
-			country: {
-				iso2: required.iso2,
-				dial_code: required.dial_code
-			},
-			phone: {
-				raw,
-				digits
-			},
-			full_phone: buildFullE164(required.dial_code, digits),
-			required,
-			details: {
-				max,
-				actual: nsn.length
-			}
-		};
-		const full = buildFullE164(required.dial_code, digits) ?? String(raw);
-		try {
-			if (!isValidPhoneNumber(full, iso2)) {
-				const parsed = parsePhoneNumberFromString(full, iso2);
-				return {
-					ok: false,
-					reason: "invalid_phone",
-					country: {
-						iso2: required.iso2,
-						dial_code: required.dial_code
-					},
-					phone: {
-						raw,
-						digits
-					},
-					full_phone: parsed?.number ?? null,
-					required,
-					details: {
-						type: parsed?.getType?.() ?? null,
-						possible: parsed?.isPossible?.() ?? null,
-						country: parsed?.country ?? null
-					}
-				};
-			}
-			const parsed = parsePhoneNumberFromString(full, iso2);
-			return {
-				ok: true,
-				reason: null,
-				country: {
-					iso2: required.iso2,
-					dial_code: required.dial_code
-				},
-				phone: {
-					raw,
-					digits
-				},
-				full_phone: parsed?.number ?? full,
-				required
-			};
-		} catch (e) {
-			return {
-				ok: false,
-				reason: "parse_failed",
-				country: {
-					iso2: required.iso2,
-					dial_code: required.dial_code
-				},
-				phone: {
-					raw,
-					digits
-				},
-				full_phone: buildFullE164(required.dial_code, digits),
-				required,
-				details: { error: e?.message ?? String(e) }
-			};
-		}
-	}
-	return {
-		countries,
-		isCountriesLoading,
-		getCountries,
-		searchCountries,
-		getCountryByValue,
-		getCountriesByDial,
-		getRequiredInfo,
-		validate
-	};
-}
-//#endregion
 //#region src/composables/useCountryDetection.ts
 /**
 * Best-effort country detection chain: IP geolocation → timezone → navigator.language → fallback.
@@ -4015,24 +3513,32 @@ function tryLocale() {
 		return null;
 	}
 }
+const inflightIpFetch = /* @__PURE__ */ new Map();
 async function tryIp(endpoint, timeoutMs) {
 	if (!isBrowser() || typeof fetch !== "function") return null;
+	const existing = inflightIpFetch.get(endpoint);
+	if (existing) return existing;
 	const controller = new AbortController();
 	const timer = setTimeout(() => controller.abort(), timeoutMs);
-	try {
-		const res = await fetch(endpoint, {
-			signal: controller.signal,
-			credentials: "omit"
-		});
-		if (!res.ok) return null;
-		const data = await res.json();
-		const code = (data.country_code ?? data.country ?? "").toString().toUpperCase();
-		return /^[A-Z]{2}$/.test(code) ? code : null;
-	} catch {
-		return null;
-	} finally {
-		clearTimeout(timer);
-	}
+	const promise = (async () => {
+		try {
+			const res = await fetch(endpoint, {
+				signal: controller.signal,
+				credentials: "omit"
+			});
+			if (!res.ok) return null;
+			const data = await res.json();
+			const code = (data.country_code ?? data.country ?? "").toString().toUpperCase();
+			return /^[A-Z]{2}$/.test(code) ? code : null;
+		} catch {
+			return null;
+		} finally {
+			clearTimeout(timer);
+			inflightIpFetch.delete(endpoint);
+		}
+	})();
+	inflightIpFetch.set(endpoint, promise);
+	return promise;
 }
 function readCache() {
 	if (!isBrowser()) return null;
@@ -4098,6 +3604,11 @@ function useCountryDetection(opts = {}) {
 }
 //#endregion
 //#region src/composables/useCountryMatching.ts
+/** Cached snapshot of every country libphonenumber knows about (~250 ISO2 codes).
+*  Used by tier 2 of `matchLeadingDialCode` as the last-resort iteration so detection
+*  works for *every* country, not just the popular ones in the bundled fallback list.
+*  Cached at module load — `getCountries()` is a static metadata table, no I/O. */
+const ALL_LIBPHONENUMBER_ISO2 = getCountries();
 /** Synchronous dial-digit → ISO2 fallback for common countries, used when the async
 *  REST Countries fetch hasn't populated `getCountriesByDial`'s index yet at setup. */
 const DIAL_TO_ISO2_FALLBACK = {
@@ -4164,6 +3675,58 @@ const DIAL_TO_ISO2_FALLBACK = {
 /** localStorage key for the user's most recently picked countries. Used as a
 *  tie-breaker when multiple countries share a dial code (e.g. all NANP). */
 const COUNTRY_RECENTS_KEY = "ali_ui_country_recents_v1";
+/** ISO2 codes iterated by tier 2 of `matchLeadingDialCode` when looking for a country
+*  that accepts a local-format input as valid. Mirrors the `FALLBACK_COUNTRIES` list in
+*  {@link usePhoneValidation} (kept in sync by tests + by being short and obvious).
+*  Order matters — earlier entries get priority when multiple countries would each
+*  validate the same input. Built around the most-populated / most-likely countries. */
+const FALLBACK_ISO2_LIST = [
+	"SA",
+	"EG",
+	"AE",
+	"US",
+	"GB",
+	"DE",
+	"FR",
+	"ES",
+	"IT",
+	"TR",
+	"RU",
+	"CN",
+	"IN",
+	"JP",
+	"KR",
+	"BR",
+	"MX",
+	"CA",
+	"AU",
+	"NG",
+	"PK",
+	"ID"
+];
+/** Build a minimal `CountryOption` from libphonenumber metadata when the async REST
+*  Countries list hasn't loaded the entry yet. Used so country **detection** works
+*  generically for any libphonenumber country, not just the ~22 in the offline
+*  fallback list. The picker will overwrite this synthetic record with the real one
+*  (with localized name + flag) as soon as `getCountries()` resolves. */
+function buildSyntheticCountry(iso2, dialDigits) {
+	const ISO2 = iso2.toUpperCase();
+	const digits = String(dialDigits).replace(/\D/g, "");
+	return {
+		label: `${ISO2} (+${digits})`,
+		value: ISO2,
+		search_key: `${ISO2.toLowerCase()} +${digits} ${digits}`,
+		raw_data: {
+			iso2: ISO2,
+			dial_code: `+${digits}`,
+			dial_digits: digits,
+			name: ISO2,
+			flag: `https://flagcdn.com/w40/${ISO2.toLowerCase()}.png`,
+			source: "fallback",
+			original: {}
+		}
+	};
+}
 function readRecents() {
 	if (typeof window === "undefined") return [];
 	try {
@@ -4209,38 +3772,75 @@ function useCountryMatching(deps) {
 		const n = Number(digits);
 		return Number.isFinite(n) ? n : null;
 	}
+	const MATCHER_CACHE_MAX = 128;
+	const matcherCache = /* @__PURE__ */ new Map();
+	function readMatcherCache(key) {
+		if (!matcherCache.has(key)) return void 0;
+		const value = matcherCache.get(key);
+		matcherCache.delete(key);
+		matcherCache.set(key, value);
+		return value;
+	}
+	function writeMatcherCache(key, value) {
+		if (matcherCache.size >= MATCHER_CACHE_MAX) {
+			const oldest = matcherCache.keys().next().value;
+			if (oldest !== void 0) matcherCache.delete(oldest);
+		}
+		matcherCache.set(key, value);
+	}
 	/** Three-tier match of the leading digits to a country:
 	*   1. libphonenumber international parse (handles NANP disambiguation).
-	*   2. libphonenumber national-format parse using `hintCountry` (handles local
-	*      formats like Egyptian `01066105963` with no dial-code prefix).
+	*   2. libphonenumber national-format parse, iterating through candidate hint
+	*      countries (handles local formats like Egyptian `01066105963` with no
+	*      dial-code prefix). Universal coverage via `getCountries()`.
 	*   3. Longest-prefix match against the dial-digits index, with the current
-	*      selection / recents as tie-breakers when multiple countries share a code. */
+	*      selection / recents as tie-breakers when multiple countries share a code.
+	*
+	* Results are LRU-cached per input + context to avoid re-paying tier-2 iteration
+	* cost when the user backspaces and retypes the same prefix. */
 	function matchLeadingDialCode(digits, options = {}) {
 		if (!digits) return null;
 		const { hintCountry, currentIso2 } = options;
+		const cacheKey = `${digits}|${hintCountry ?? ""}|${currentIso2 ?? ""}`;
+		const cached = readMatcherCache(cacheKey);
+		if (cached !== void 0) return cached;
+		const result = runMatch(digits, hintCountry, currentIso2);
+		writeMatcherCache(cacheKey, result);
+		return result;
+	}
+	function runMatch(digits, hintCountry, currentIso2) {
 		try {
 			const parsed = parsePhoneNumberFromString(`+${digits}`);
-			if (parsed?.country && parsed.countryCallingCode) {
-				const parsedCountry = getCountryByValue(parsed.country);
-				if (parsedCountry) return {
-					country: parsedCountry,
-					nationalNumber: String(parsed.nationalNumber ?? "")
-				};
-			}
-		} catch {}
-		if (hintCountry && digits.length >= 4) try {
-			const parsed = parsePhoneNumberFromString(digits, hintCountry);
-			if (parsed?.isValid()) {
-				const matched = getCountryByValue(parsed.country || hintCountry);
-				if (matched) return {
-					country: matched,
-					nationalNumber: String(parsed.nationalNumber ?? "")
-				};
-			}
+			if (parsed?.country && parsed.countryCallingCode) return {
+				country: getCountryByValue(parsed.country) ?? buildSyntheticCountry(parsed.country, String(parsed.countryCallingCode)),
+				nationalNumber: String(parsed.nationalNumber ?? "")
+			};
 		} catch {}
+		if (digits.length >= 4) {
+			const candidates = /* @__PURE__ */ new Set();
+			if (hintCountry) candidates.add(hintCountry.toUpperCase());
+			if (currentIso2) candidates.add(currentIso2.toUpperCase());
+			for (const recent of readRecents()) candidates.add(recent.toUpperCase());
+			for (const fallback of FALLBACK_ISO2_LIST) candidates.add(fallback);
+			for (const all of ALL_LIBPHONENUMBER_ISO2) candidates.add(all);
+			for (const iso2 of candidates) try {
+				const parsed = parsePhoneNumberFromString(digits, iso2);
+				if (parsed?.isValid()) {
+					const resolvedIso2 = parsed.country || iso2;
+					return {
+						country: getCountryByValue(resolvedIso2) ?? buildSyntheticCountry(resolvedIso2, String(parsed.countryCallingCode ?? "")),
+						nationalNumber: String(parsed.nationalNumber ?? "")
+					};
+				}
+			} catch {}
+		}
 		for (let len = Math.min(3, digits.length); len >= 1; len--) {
 			const prefix = digits.slice(0, len);
-			const group = getCountriesByDial(prefix);
+			let group = getCountriesByDial(prefix);
+			if (!group.length) {
+				const iso2 = DIAL_TO_ISO2_FALLBACK[prefix];
+				if (iso2) group = [getCountryByValue(iso2) ?? buildSyntheticCountry(iso2, prefix)];
+			}
 			if (!group.length) continue;
 			const nationalNumber = digits.slice(prefix.length);
 			if (group.length === 1) return {
@@ -4312,18 +3912,36 @@ function useTelInputValidation(deps, inputs, config) {
 		phone: inputs.phone.value ?? "",
 		locale: config.locale()
 	}));
+	const externalErrorActive = computed(() => {
+		const e = config.externalError();
+		return typeof e === "string" && e.length > 0;
+	});
 	const validationState = computed(() => {
+		if (externalErrorActive.value) return "error";
 		if (!inputs.phone.value) return "idle";
 		return validation.value.ok ? "valid" : "error";
 	});
-	const visibleValidationState = computed(() => inputs.hasFinishedTyping.value ? validationState.value : "idle");
+	const visibleValidationState = computed(() => {
+		if (externalErrorActive.value) return "error";
+		const mode = config.validateOn() ?? "change";
+		if (mode === "eager") return validationState.value;
+		if (mode === "blur" && !inputs.hasBlurred.value) return "idle";
+		return inputs.hasFinishedTyping.value ? validationState.value : "idle";
+	});
 	const errorMessage = computed(() => {
+		const ext = config.externalError();
+		if (typeof ext === "string" && ext.length > 0) return ext;
 		const v = validation.value;
 		if (v.ok || !v.reason) return null;
 		if (!inputs.phone.value) return null;
 		return config.errorMessages()?.[v.reason] ?? inputs.messages.value.errorMessages[v.reason];
 	});
-	const showError = computed(() => Boolean(config.showValidation() && inputs.hasFinishedTyping.value && errorMessage.value));
+	const showError = computed(() => {
+		if (!errorMessage.value) return false;
+		if (externalErrorActive.value) return true;
+		if (!config.showValidation()) return false;
+		return visibleValidationState.value === "error";
+	});
 	return {
 		validation,
 		required,
@@ -4339,54 +3957,88 @@ function useTelInputValidation(deps, inputs, config) {
 	};
 }
 //#endregion
-//#region src/types.ts
-const aTelInputVariants = cva("a-tel-input__field", {
-	variants: { size: {
-		xs: "",
-		sm: "",
-		md: "",
-		lg: "",
-		xl: ""
-	} },
-	defaultVariants: { size: "md" }
-});
-const DEFAULT_ERROR_MESSAGES = {
-	missing_country: "Please select a country.",
-	country_not_supported: "This country is not supported.",
-	phone_has_non_digits: "Phone number can only contain digits.",
-	too_short: "Phone number is too short.",
-	too_long: "Phone number is too long.",
-	invalid_phone: "Phone number is invalid.",
-	parse_failed: "Could not parse phone number."
-};
-/** English defaults for every {@link TelInputMessages} key. */
-const DEFAULT_MESSAGES = {
-	searchPlaceholder: "Search country or +code…",
-	emptyText: "No countries found.",
-	loadingText: "Loading countries…",
-	suggestedLabel: "Suggested",
-	allCountriesLabel: "All countries",
-	errorMessages: DEFAULT_ERROR_MESSAGES,
-	countryLabel: "Country",
-	selectCountryLabel: "Select country",
-	phoneInputLabel: "Phone number"
-};
+//#region src/composables/useCountrySelection.ts
 /**
-* Merge a partial `messages` override onto the English defaults. Used internally by
-* `ATelInput` to resolve a complete {@link TelInputMessages} object.
+* The picker selection state machine for {@link ATelInput}, consolidated into a
+* single composable so the component doesn't have to juggle three boolean flags
+* (`userPickedCountry` / `autoSettingCountry` / `inputDetectionApplied`) and
+* reason about their pairwise interactions.
+*
+* Every write to the selection goes through {@link UseCountrySelectionReturn.set},
+* which records both the new ISO2 and the *origin* of the change. That makes the
+* downstream decision — should detection re-route the picker on the next typed-input
+* burst? — a one-liner: `if (detectionLocked.value) return;`.
 */
-function resolveMessages(input) {
-	if (!input) return DEFAULT_MESSAGES;
+function useCountrySelection() {
+	const iso2 = ref("");
+	const source = ref("none");
+	function set(nextIso2, nextSource) {
+		iso2.value = nextIso2;
+		source.value = nextSource;
+	}
+	function clear() {
+		iso2.value = "";
+		source.value = "none";
+	}
 	return {
-		...DEFAULT_MESSAGES,
-		...input,
-		errorMessages: {
-			...DEFAULT_ERROR_MESSAGES,
-			...input.errorMessages
-		}
+		iso2,
+		source,
+		set,
+		clear,
+		detectionLocked: computed(() => source.value === "picker" || source.value === "input")
 	};
 }
 //#endregion
+//#region src/composables/useSyncedModel.ts
+/**
+* Two-way bidirectional sync between a `defineModel` ref and internal component
+* state — with the **echo-loop guard** built in. Solves a recurring class of
+* bugs in this component where two watchers (external→internal and
+* internal→external) would fight each other and rewrite values the user just
+* typed.
+*
+* Mechanics:
+*
+*   1. When any of `triggers` change AND we're not currently applying an
+*      external write, recompute the model value via `compose()` and write it
+*      into `model`. Stamp `lastEmitted` first so we recognise the echo.
+*   2. When `model` changes AND the new value isn't the echo of our last emit,
+*      apply it into internal state via `apply()`. The `applying` flag is held
+*      for the duration of `apply()` so step (1) skips while we mutate.
+*
+* Used for:
+*   - `modelValue` (E.164 string) ↔ `phone` + `selectedIso2`.
+*   - `country` (dial-number) ↔ `selectedIso2`.
+*
+* The hand-rolled equivalents (`applyingModelValue` / `lastEmittedModelValue`
+* plus the country↔iso2 watcher pair with `autoSettingCountry`) collapse into
+* two calls to this helper.
+*/
+function useSyncedModel(options) {
+	const { model, triggers, compose, apply } = options;
+	const isEqual = options.isEqual ?? Object.is;
+	let applying = false;
+	let lastEmitted = { __unset: true };
+	const isEcho = (v) => typeof lastEmitted === "object" && lastEmitted !== null && "__unset" in lastEmitted ? false : isEqual(v, lastEmitted);
+	watch(model, (next) => {
+		if (isEcho(next)) return;
+		applying = true;
+		try {
+			apply(next);
+		} finally {
+			applying = false;
+		}
+	}, { immediate: true });
+	watch(triggers, () => {
+		if (applying) return;
+		const next = compose();
+		if (!isEqual(next, model.value)) {
+			lastEmitted = next;
+			model.value = next;
+		}
+	}, { flush: "post" });
+}
+//#endregion
 //#region ../AResponsivePopover/dist/index.js
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -16951,11 +16603,6 @@ const _sfc_main$2$2 = /* @__PURE__ */ defineComponent({
 		const open = useModel(__props, "open");
 		const isDesktop = useMediaQuery(() => props.breakpoint);
 		/**
-		* Pre-imported on both branches — do NOT lazy-load. Switching the component identity at runtime
-		* means we still hydrate the right tree client-side.
-		*/
-		const Root = computed(() => isDesktop.value ? APopover_default : ADrawer_default);
-		/**
 		* Per-branch `modal` resolution — the two roots interpret the prop differently:
 		*
 		*   APopover (desktop, reka-ui): `modal=true` triggers `PopoverContentModal` + its
@@ -16972,7 +16619,7 @@ const _sfc_main$2$2 = /* @__PURE__ */ defineComponent({
 			return props.scrollLock === "body";
 		});
 		const drawerModal = computed(() => props.modal !== false);
-		const rootModal = computed(() => isDesktop.value ? rekaModal.value : drawerModal.value);
+		const drawerNoBodyStyles = computed(() => props.scrollLock !== "body");
 		provideResponsivePopoverContext({
 			open: computed(() => open.value ?? false),
 			isDesktop: computed(() => isDesktop.value),
@@ -16982,10 +16629,15 @@ const _sfc_main$2$2 = /* @__PURE__ */ defineComponent({
 			props,
 			open,
 			isDesktop,
-			Root,
 			rekaModal,
 			drawerModal,
-			rootModal
+			drawerNoBodyStyles,
+			get APopover() {
+				return APopover_default;
+			},
+			get ADrawer() {
+				return ADrawer_default;
+			}
 		};
 		Object.defineProperty(__returned__, "__isScriptSetup", {
 			enumerable: false,
@@ -16995,15 +16647,30 @@ const _sfc_main$2$2 = /* @__PURE__ */ defineComponent({
 	}
 });
 function _sfc_render$2$2(_ctx, _cache, $props, $setup, $data, $options) {
-	return openBlock(), createBlock(resolveDynamicComponent($setup.Root), {
+	return $setup.isDesktop ? (openBlock(), createBlock($setup["APopover"], {
+		key: 0,
 		open: $setup.open,
 		"onUpdate:open": _cache[0] || (_cache[0] = ($event) => $setup.open = $event),
-		modal: $setup.rootModal,
+		modal: $setup.rekaModal,
 		"data-slot": "responsive-popover"
 	}, {
-		default: withCtx(() => [renderSlot(_ctx.$slots, "default", { isDesktop: $setup.isDesktop })]),
+		default: withCtx(() => [renderSlot(_ctx.$slots, "default", { isDesktop: true })]),
 		_: 3
-	}, 40, ["open", "modal"]);
+	}, 8, ["open", "modal"])) : (openBlock(), createBlock($setup["ADrawer"], {
+		key: 1,
+		open: $setup.open,
+		"onUpdate:open": _cache[1] || (_cache[1] = ($event) => $setup.open = $event),
+		modal: $setup.drawerModal,
+		"no-body-styles": $setup.drawerNoBodyStyles,
+		"data-slot": "responsive-popover"
+	}, {
+		default: withCtx(() => [renderSlot(_ctx.$slots, "default", { isDesktop: false })]),
+		_: 3
+	}, 8, [
+		"open",
+		"modal",
+		"no-body-styles"
+	]));
 }
 var AResponsivePopover_default = /* @__PURE__ */ export_helper_default$3(_sfc_main$2$2, [["render", _sfc_render$2$2], ["__file", "/Users/alikhalill/Desktop/my-projects/ali-nuxt-toolkit/packages/ui-components/AResponsivePopover/src/components/AResponsivePopover.vue"]]);
 const _sfc_main$1$2 = /* @__PURE__ */ defineComponent({
@@ -17116,7 +16783,7 @@ const _sfc_main$9 = /* @__PURE__ */ defineComponent({
 				if (typeof document === "undefined") return [];
 				return Array.from(document.querySelectorAll("[data-responsive-popover-scroll-container=\"true\"]"));
 			},
-			active: computed(() => !!ctx?.open.value && isDesktop.value && scrollLockMode.value === "events")
+			active: computed(() => !!ctx?.open.value && scrollLockMode.value === "events")
 		});
 		const __returned__ = {
 			props,
@@ -17162,7 +16829,8 @@ function _sfc_render$9(_ctx, _cache, $props, $setup, $data, $options) {
 	])) : (openBlock(), createBlock($setup["ADrawerContent"], {
 		key: 1,
 		class: normalizeClass($setup.mergedClass),
-		"data-slot": "responsive-popover-content"
+		"data-slot": "responsive-popover-content",
+		"data-responsive-popover-scroll-container": "true"
 	}, {
 		default: withCtx(() => [renderSlot(_ctx.$slots, "default")]),
 		_: 3
@@ -17821,7 +17489,7 @@ const _hoisted_6$1 = {
 };
 const _hoisted_7$1 = { class: "a-country-select__list" };
 const _hoisted_8$1 = { class: "a-country-select__loading" };
-const _hoisted_9 = { class: "a-country-select__empty" };
+const _hoisted_9$1 = { class: "a-country-select__empty" };
 const _hoisted_10 = {
 	key: 0,
 	"data-slot": "country-select-group",
@@ -17919,7 +17587,7 @@ function _sfc_render$1(_ctx, _cache, $props, $setup, $data, $options) {
 				createElementVNode("div", _hoisted_7$1, [$setup.isCountriesLoading && $setup.effectiveCountries.length === 0 ? renderSlot(_ctx.$slots, "loading", { key: 0 }, () => [createElementVNode("div", _hoisted_8$1, toDisplayString($setup.props.loadingText), 1)], true) : $setup.isSearching && $setup.filtered.length === 0 ? renderSlot(_ctx.$slots, "empty", {
 					key: 1,
 					query: $setup.search
-				}, () => [createElementVNode("div", _hoisted_9, toDisplayString($setup.props.emptyText), 1)], true) : (openBlock(), createElementBlock(Fragment, { key: 2 }, [
+				}, () => [createElementVNode("div", _hoisted_9$1, toDisplayString($setup.props.emptyText), 1)], true) : (openBlock(), createElementBlock(Fragment, { key: 2 }, [
 					createCommentVNode(" Suggested group "),
 					$setup.suggested.length > 0 ? (openBlock(), createElementBlock("section", _hoisted_10, [renderSlot(_ctx.$slots, "group-header", {
 						label: $setup.props.suggestedLabel,
@@ -18048,6 +17716,27 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
 			required: false,
 			skipCheck: true
 		},
+		modelValue: {
+			type: String,
+			required: false
+		},
+		name: {
+			type: String,
+			required: false
+		},
+		error: {
+			type: [String, null],
+			required: false
+		},
+		validating: {
+			type: Boolean,
+			required: false
+		},
+		validateOn: {
+			type: String,
+			required: false,
+			default: "change"
+		},
 		placeholder: {
 			type: String,
 			required: false,
@@ -18190,28 +17879,65 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
 			type: [Number, null],
 			default: null
 		},
-		"countryModifiers": {}
+		"countryModifiers": {},
+		"modelValue": {
+			type: String,
+			default: ""
+		},
+		"modelModifiers": {}
 	}),
-	emits: ["update:phone", "update:country"],
-	setup(__props, { expose: __expose }) {
+	emits: /* @__PURE__ */ mergeModels([
+		"update:modelValue",
+		"update:phone",
+		"update:country",
+		"blur",
+		"focus"
+	], [
+		"update:phone",
+		"update:country",
+		"update:modelValue"
+	]),
+	setup(__props, { expose: __expose, emit: __emit }) {
 		const props = __props;
+		const emit = __emit;
 		const phone = useModel(__props, "phone");
 		/** Public `v-model:country` — the **dial number** (e.g. `20` for Egypt, `44` for the UK,
 		*  `1` for the NANP block). `null` means no country selected. Internally the component
 		*  tracks a richer ISO2 code (`selectedIso2`) because dial codes alone can't disambiguate
 		*  NANP (`+1` covers 25+ countries) — the picker still needs an exact country. */
 		const country = useModel(__props, "country");
-		/** Internal source of truth — the ISO2 alpha-2 code of the picker selection. Synced with
-		*  `country` (dial number) via watchers below. */
-		const selectedIso2 = ref("");
+		/**
+		* Default v-model — the canonical **E.164** string (e.g. `'+201066105963'`).
+		*
+		* Single-string contract for VeeValidate's `<Field v-slot="{ field }">` pattern
+		* (`v-bind="field"`), native `<form>` submission, or any `v-model="phoneE164"`
+		* consumer. Bind it with:
+		*
+		*   <ATelInput v-model="phoneE164" />
+		*
+		*   <VeeField v-slot="{ field, errors }" name="phone">
+		*     <ATelInput v-bind="field" :error="errors[0]" />
+		*   </VeeField>
+		*
+		* When set externally, the value is parsed via libphonenumber-js → the country
+		* picker and the digits-only `phone` model are derived from it. When the user
+		* types or picks a country, the composed E.164 is written back out. Stays in
+		* sync with `v-model:phone` / `v-model:country` — you can use either contract.
+		*/
+		const modelValue = useModel(__props, "modelValue");
+		/** The picker selection state machine — `iso2` is the internal source of truth, `source`
+		*  records where the current selection came from, `detectionLocked` answers "should
+		*  typed-input detection re-route the picker on the next burst?". Single mutator: `set`.
+		*  Replaces the historical flag soup (`userPickedCountry` / `autoSettingCountry` /
+		*  `inputDetectionApplied`). */
+		const selection = useCountrySelection();
+		const selectedIso2 = selection.iso2;
 		const { getCountries, validate, getRequiredInfo, getCountryByValue, getCountriesByDial } = usePhoneValidation();
 		const { resolveCountryIdentifier, dialNumberFor, matchLeadingDialCode } = useCountryMatching({
 			getCountryByValue,
 			getCountriesByDial
 		});
 		getCountries();
-		const userPickedCountry = ref(false);
-		const autoSettingCountry = ref(false);
 		/** Silently resolved via IP/timezone/locale when `detectFromInput` is on — used as a hint
 		*  so local-format numbers (e.g. Egyptian `01066105963`) can be parsed without a `+` prefix.
 		*  Seeded from `defaultCountry` so it has a usable value before async detection resolves. */
@@ -18225,18 +17951,28 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
 				currentIso2: selectedIso2.value
 			});
 		}
+		/** User explicitly picked a country from the picker — locks the selection so subsequent
+		*  typed-input detection cannot churn the picker. */
+		function onPickerPick(iso2) {
+			selection.set(iso2, "picker");
+		}
 		const typing = useTypingPhase({
 			debounceMs: computed(() => Math.max(0, props.detectDebounceMs)),
 			onSettle: () => {
 				if (!props.detectFromInput) return;
-				if (userPickedCountry.value || selectedIso2.value) return;
+				if (selection.detectionLocked.value) return;
 				const current = phone.value;
 				if (!current) return;
+				const typedInternational = (displayValue.value ?? "").trimStart().startsWith("+");
+				if (selectedIso2.value && !typedInternational) return;
 				typing.markDetectionAttempt();
 				const match = tryMatchPhone(current);
 				if (!match) return;
-				autoSettingCountry.value = true;
-				selectedIso2.value = match.country.value;
+				if (match.country.value === selectedIso2.value && match.nationalNumber === phone.value) {
+					selection.source.value = "input";
+					return;
+				}
+				selection.set(match.country.value, "input");
 				phone.value = match.nationalNumber;
 			}
 		});
@@ -18247,8 +17983,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
 				const seed = resolveCountryIdentifier(props.defaultCountry);
 				if (seed) {
 					inferredCountry.value = seed;
-					autoSettingCountry.value = true;
-					selectedIso2.value = seed;
+					selection.set(seed, "default");
 					return;
 				}
 			}
@@ -18267,43 +18002,31 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
 			const iso2 = detected ? detected.toUpperCase() : "";
 			if (props.detectFromInput) {
 				inferredCountry.value = iso2;
-				if (phone.value && !userPickedCountry.value && !selectedIso2.value) {
+				if (phone.value && !selection.detectionLocked.value && !selectedIso2.value) {
 					const match = tryMatchPhone(phone.value);
 					if (match) {
-						autoSettingCountry.value = true;
-						selectedIso2.value = match.country.value;
+						selection.set(match.country.value, "input");
 						phone.value = match.nationalNumber;
 					}
 				}
 				return;
 			}
-			if (!selectedIso2.value && iso2) {
-				autoSettingCountry.value = true;
-				selectedIso2.value = iso2;
-			}
+			if (!selectedIso2.value && iso2) selection.set(iso2, "env");
 		});
-		/** External → internal: when the caller mutates `v-model:country` (dial number), resolve
-		*  it to an ISO2. If the current ISO2 already maps to this dial (e.g. user has Canada
-		*  selected and the caller writes back `1`), keep the existing selection — don't churn it. */
-		watch(country, (next) => {
-			if (next == null) {
-				if (selectedIso2.value) selectedIso2.value = "";
-				return;
+		useSyncedModel({
+			model: country,
+			triggers: [selectedIso2],
+			compose: () => selectedIso2.value ? dialNumberFor(selectedIso2.value) : null,
+			apply: (next) => {
+				if (next == null) {
+					selection.clear();
+					return;
+				}
+				if (dialNumberFor(selectedIso2.value) === next) return;
+				const iso2 = resolveCountryIdentifier(String(next));
+				if (iso2) selection.set(iso2, "external");
 			}
-			if (dialNumberFor(selectedIso2.value) === next) return;
-			const iso2 = resolveCountryIdentifier(String(next));
-			if (iso2) selectedIso2.value = iso2;
-		}, { immediate: true });
-		/** Internal → external: keep `country` (dial number) in lockstep with `selectedIso2`, and
-		*  flag "user manually picked from picker" when the change isn't one we initiated.
-		*  `flush: 'sync'` so the `autoSettingCountry` guard is reliable. */
-		watch(selectedIso2, (iso2, prev) => {
-			const wasAutoSet = autoSettingCountry.value;
-			autoSettingCountry.value = false;
-			const nextDial = dialNumberFor(iso2);
-			if (country.value !== nextDial) country.value = nextDial;
-			if (!wasAutoSet && props.detectFromInput && iso2 && prev !== iso2) userPickedCountry.value = true;
-		}, { flush: "sync" });
+		});
 		/** The string shown in the `<input>`. Deliberately decoupled from `phone` (the digits-only
 		*  model) so the visible field is NOT rewritten mid-edit — non-digits / alternative numerals
 		*  are normalized into `phone` immediately, but the displayed value is only cleaned up once
@@ -18312,6 +18035,29 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
 		/** Set when the in-flight `phone` change came from the user typing — tells the `phone`
 		*  watcher to leave `displayValue` alone (the user is still editing it). */
 		let phoneEditedByInput = false;
+		useSyncedModel({
+			model: modelValue,
+			triggers: [phone, selectedIso2],
+			compose: () => {
+				if (!selectedIso2.value || !phone.value) return "";
+				return validate({
+					country: { iso2: selectedIso2.value },
+					phone: phone.value
+				}).full_phone ?? "";
+			},
+			apply: (next) => {
+				const trimmed = String(next ?? "").trim();
+				if (!trimmed) {
+					if (phone.value !== "") phone.value = "";
+					if (selectedIso2.value !== "") selection.clear();
+					return;
+				}
+				const parsed = parsePhoneNumberFromString(trimmed.startsWith("+") ? trimmed : `+${trimmed.replace(/^\+/, "")}`);
+				if (!parsed || !parsed.country) return;
+				if (selectedIso2.value !== parsed.country) selection.set(parsed.country, "external");
+				if (phone.value !== parsed.nationalNumber) phone.value = parsed.nationalNumber;
+			}
+		});
 		function commitPhone(value) {
 			phoneEditedByInput = true;
 			phone.value = value;
@@ -18322,11 +18068,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
 			const cleaned = normalizeDigits(target.value).replace(/\D/g, "");
 			if (!cleaned) {
 				typing.reset();
-				if (props.detectFromInput) {
-					autoSettingCountry.value = true;
-					selectedIso2.value = "";
-					userPickedCountry.value = false;
-				}
+				if (props.detectFromInput) selection.clear();
 				commitPhone("");
 				return;
 			}
@@ -18359,6 +18101,8 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
 		*  `undefined` so it inherits from the page. The field row itself is always LTR so the
 		*  dial prefix / digits / flag trigger keep a consistent order. */
 		const dirAttr = computed(() => props.dir === "ltr" || props.dir === "rtl" ? props.dir : void 0);
+		/** Set to `true` the first time the input is blurred. Drives `validateOn: 'blur'`. */
+		const hasBlurred = ref(false);
 		const { validation, required, validationState, visibleValidationState, errorMessage, showError, showHint, selectedDialCode } = useTelInputValidation({
 			validate,
 			getRequiredInfo,
@@ -18367,15 +18111,35 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
 			phone,
 			selectedIso2,
 			hasFinishedTyping,
+			hasBlurred,
 			messages
 		}, {
 			locale: () => props.locale,
 			showValidation: () => props.showValidation,
-			errorMessages: () => props.errorMessages
+			errorMessages: () => props.errorMessages,
+			validateOn: () => props.validateOn,
+			externalError: () => props.error
 		});
 		const effectivePlaceholder = computed(() => props.placeholder || required.value?.format_hint || messages.value.phoneInputLabel);
 		const helperId = useId();
 		const describedBy = computed(() => showError.value || showHint.value ? helperId : void 0);
+		const inputRef = ref(null);
+		function handleBlur(e) {
+			hasBlurred.value = true;
+			emit("blur", e);
+		}
+		function handleFocus(e) {
+			emit("focus", e);
+		}
+		function focus(options) {
+			inputRef.value?.focus(options);
+		}
+		function blur() {
+			inputRef.value?.blur();
+		}
+		function select() {
+			inputRef.value?.select();
+		}
 		__expose({
 			validation,
 			required,
@@ -18384,12 +18148,18 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
 			visibleValidationState,
 			isDetecting,
 			hasFinishedTyping,
-			detectionAttempted
+			detectionAttempted,
+			focus,
+			blur,
+			select
 		});
 		const __returned__ = {
 			props,
+			emit,
 			phone,
 			country,
+			modelValue,
+			selection,
 			selectedIso2,
 			getCountries,
 			validate,
@@ -18399,10 +18169,9 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
 			resolveCountryIdentifier,
 			dialNumberFor,
 			matchLeadingDialCode,
-			userPickedCountry,
-			autoSettingCountry,
 			inferredCountry,
 			tryMatchPhone,
+			onPickerPick,
 			typing,
 			isDetecting,
 			hasFinishedTyping,
@@ -18419,6 +18188,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
 			handlePhoneChange,
 			messages,
 			dirAttr,
+			hasBlurred,
 			validation,
 			required,
 			validationState,
@@ -18430,6 +18200,12 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
 			effectivePlaceholder,
 			helperId,
 			describedBy,
+			inputRef,
+			handleBlur,
+			handleFocus,
+			focus,
+			blur,
+			select,
 			get cn() {
 				return cn$2;
 			},
@@ -18471,25 +18247,34 @@ const _hoisted_4 = {
 };
 const _hoisted_5 = [
 	"value",
+	"name",
 	"disabled",
 	"placeholder",
 	"aria-label",
 	"aria-invalid",
 	"aria-describedby",
+	"aria-errormessage",
+	"aria-busy",
 	"data-has-dial"
 ];
 const _hoisted_6 = {
+	key: 0,
+	class: "a-tel-input__validating",
+	"data-slot": "tel-input-validating",
+	"aria-hidden": "true"
+};
+const _hoisted_7 = {
 	key: 0,
 	class: "a-tel-input__detecting",
 	"aria-hidden": "true",
 	"data-slot": "tel-input-detecting"
 };
-const _hoisted_7 = {
+const _hoisted_8 = {
 	key: 0,
 	class: "a-tel-input__country-wrapper",
 	"data-slot": "tel-input-country-wrapper"
 };
-const _hoisted_8 = ["id"];
+const _hoisted_9 = ["id"];
 function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) {
 	return openBlock(), createElementBlock("div", {
 		class: normalizeClass($setup.cn("a-tel-input", _ctx.$attrs.class)),
@@ -18507,31 +18292,41 @@ function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) {
 			renderSlot(_ctx.$slots, "prefix", {}, void 0, true),
 			$setup.selectedDialCode ? (openBlock(), createElementBlock("span", _hoisted_4, toDisplayString($setup.selectedDialCode), 1)) : createCommentVNode("v-if", true),
 			createElementVNode("input", {
+				ref: "inputRef",
 				value: $setup.displayValue,
 				type: "tel",
 				inputmode: "numeric",
 				autocomplete: "tel",
 				dir: "ltr",
 				"data-slot": "tel-input-field",
+				name: $setup.props.name,
 				disabled: $setup.props.disabled || $setup.props.loading,
 				placeholder: $setup.effectivePlaceholder,
 				"aria-label": $setup.messages.phoneInputLabel,
 				"aria-invalid": $setup.visibleValidationState === "error" || void 0,
 				"aria-describedby": $setup.describedBy,
+				"aria-errormessage": $setup.visibleValidationState === "error" ? $setup.helperId : void 0,
+				"aria-busy": $setup.props.validating || void 0,
 				class: normalizeClass($setup.cn("a-tel-input__input", $setup.props.inputClass)),
 				"data-has-dial": $setup.selectedDialCode ? "" : void 0,
 				onInput: $setup.handlePhoneInput,
-				onChange: $setup.handlePhoneChange
+				onChange: $setup.handlePhoneChange,
+				onBlur: $setup.handleBlur,
+				onFocus: $setup.handleFocus
 			}, null, 42, _hoisted_5),
+			createCommentVNode(" Async-validation spinner (e.g. server-side \"phone exists?\" check). Independent\n             of `isDetecting` (which is for country detection) so both can be shown without\n             interfering. Lives next to the input and never disables it. "),
+			createVNode(Transition, { name: "a-tell-detect" }, {
+				default: withCtx(() => [$setup.props.validating ? (openBlock(), createElementBlock("div", _hoisted_6, [renderSlot(_ctx.$slots, "validating", {}, () => [createVNode($setup["SpinnerIcon"], { class: "a-tel-input__detecting-icon" })], true)])) : createCommentVNode("v-if", true)]),
+				_: 3
+			}),
 			createCommentVNode(" Detection-in-flight spinner — shown only during the first debounce window,\n             before the picker has appeared. Once the picker is visible (success OR a failed\n             attempt that revealed the empty picker) we stop re-flashing on every keystroke. "),
 			createVNode(Transition, { name: "a-tell-detect" }, {
-				default: withCtx(() => [$setup.isDetecting && !$setup.selectedIso2 && !$setup.detectionAttempted ? (openBlock(), createElementBlock("div", _hoisted_6, [renderSlot(_ctx.$slots, "detecting", {}, () => [createVNode($setup["SpinnerIcon"], { class: "a-tel-input__detecting-icon" })], true)])) : createCommentVNode("v-if", true)]),
+				default: withCtx(() => [$setup.isDetecting && !$setup.selectedIso2 && !$setup.detectionAttempted ? (openBlock(), createElementBlock("div", _hoisted_7, [renderSlot(_ctx.$slots, "detecting", {}, () => [createVNode($setup["SpinnerIcon"], { class: "a-tel-input__detecting-icon" })], true)])) : createCommentVNode("v-if", true)]),
 				_: 3
 			}),
 			createVNode(Transition, { name: "a-tell-country" }, {
-				default: withCtx(() => [!$setup.props.detectFromInput || $setup.selectedIso2 || $setup.detectionAttempted ? (openBlock(), createElementBlock("div", _hoisted_7, [createVNode($setup["ACountrySelect"], {
+				default: withCtx(() => [!$setup.props.detectFromInput || $setup.selectedIso2 || $setup.detectionAttempted ? (openBlock(), createElementBlock("div", _hoisted_8, [createVNode($setup["ACountrySelect"], {
 					selected: $setup.selectedIso2,
-					"onUpdate:selected": _cache[0] || (_cache[0] = ($event) => $setup.selectedIso2 = $event),
 					"allowed-dial-codes": $setup.props.allowedDialCodes,
 					disabled: $setup.props.disabled || $setup.props.loading,
 					size: $setup.props.size,
@@ -18542,6 +18337,7 @@ function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) {
 					"suggested-label": $setup.messages.suggestedLabel,
 					"all-countries-label": $setup.messages.allCountriesLabel,
 					"country-label": $setup.messages.countryLabel,
+					"onUpdate:selected": $setup.onPickerPick,
 					"select-country-label": $setup.messages.selectCountryLabel,
 					"flag-url": $setup.props.flagUrl,
 					searcher: $setup.props.searcher,
@@ -18648,7 +18444,7 @@ function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) {
 		}, () => [createElementVNode("p", {
 			"data-slot": "tel-input-hint",
 			class: normalizeClass($setup.cn("a-tel-input__hint", $setup.props.hintClass))
-		}, toDisplayString($setup.required.format_hint), 3)], true) : createCommentVNode("v-if", true)], 8, _hoisted_8)
+		}, toDisplayString($setup.required.format_hint), 3)], true) : createCommentVNode("v-if", true)], 8, _hoisted_9)
 	], 10, _hoisted_1);
 }
 var ATelInput_default = /* @__PURE__ */ export_helper_default(_sfc_main, [
@@ -18657,6 +18453,6 @@ var ATelInput_default = /* @__PURE__ */ export_helper_default(_sfc_main, [
 	["__file", "/Users/alikhalill/Desktop/my-projects/ali-nuxt-toolkit/packages/ui-components/ATelInput/src/components/ATelInput.vue"]
 ]);
 //#endregion
-export { ACountryFlag_default as ACountryFlag, ACountrySelect_default as ACountrySelect, ATelInput_default as ATelInput, COUNTRY_RECENTS_KEY, DEFAULT_ERROR_MESSAGES, DEFAULT_MESSAGES, DIAL_TO_ISO2_FALLBACK, LOCALE_DIGIT_RANGES, aTelInputVariants, defaultFlagUrl, detectCountry, localizeCountries, normalizeDigits, resolveMessages, useCountryDetection, useCountryMatching, usePhoneValidation, useTelInputValidation, useTypingPhase };
+export { ACountryFlag_default as ACountryFlag, ACountrySelect_default as ACountrySelect, ATelInput_default as ATelInput, COUNTRY_RECENTS_KEY, DEFAULT_ERROR_MESSAGES, DEFAULT_MESSAGES, DIAL_TO_ISO2_FALLBACK, FALLBACK_ISO2_LIST, LOCALE_DIGIT_RANGES, aTelInputVariants, defaultFlagUrl, detectCountry, localizeCountries, normalizeDigits, resolveMessages, useCountryDetection, useCountryMatching, useCountrySelection, usePhoneValidation, useSyncedModel, useTelInputValidation, useTypingPhase };
 
 //# sourceMappingURL=index.js.map