@alikhalilll/a-tel-input 1.0.2 → 1.1.0

package/src/composables/useCountryMatching.ts

@@ -1,6 +1,12 @@
-import { parsePhoneNumberFromString, type CountryCode } from 'libphonenumber-js';
+import { getCountries, parsePhoneNumberFromString, type CountryCode } from 'libphonenumber-js';
 import type { CountryOption } from './usePhoneValidation';
 
+/** 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: readonly string[] = 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. */
 export const DIAL_TO_ISO2_FALLBACK: Record<string, string> = {
@@ -69,6 +75,36 @@ export const DIAL_TO_ISO2_FALLBACK: Record<string, string> = {
  *  tie-breaker when multiple countries share a dial code (e.g. all NANP). */
 export 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. */
+export const FALLBACK_ISO2_LIST: readonly string[] = [
+  'SA',
+  'EG',
+  'AE',
+  'US',
+  'GB',
+  'DE',
+  'FR',
+  'ES',
+  'IT',
+  'TR',
+  'RU',
+  'CN',
+  'IN',
+  'JP',
+  'KR',
+  'BR',
+  'MX',
+  'CA',
+  'AU',
+  'NG',
+  'PK',
+  'ID',
+];
+
 export interface DialMatch {
   country: CountryOption;
   /** The national significant number — what the phone input should hold, with both the
@@ -85,6 +121,30 @@ export interface MatchLeadingDialCodeOptions {
   currentIso2?: string;
 }
 
+/** 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: string, dialDigits: string): CountryOption {
+  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(): string[] {
   if (typeof window === 'undefined') return [];
   try {
@@ -145,12 +205,41 @@ export function useCountryMatching(deps: CountryMatchingDeps) {
     return Number.isFinite(n) ? n : null;
   }
 
+  // LRU cache of recent matcher results. Tier 2 iterates over ~250 countries in the
+  // worst case (~25–250 ms of parsing); without this cache, every debounce settle on
+  // an unmatched input would re-pay that cost. Keyed by the full input + context so
+  // user picks / recents updates don't return stale matches. Capped to a small size —
+  // typing typically reuses a few prefixes, no need for unbounded memory.
+  const MATCHER_CACHE_MAX = 128;
+  const matcherCache = new Map<string, DialMatch | null>();
+
+  function readMatcherCache(key: string): DialMatch | null | undefined {
+    if (!matcherCache.has(key)) return undefined;
+    // Refresh LRU order by re-inserting.
+    const value = matcherCache.get(key)!;
+    matcherCache.delete(key);
+    matcherCache.set(key, value);
+    return value;
+  }
+
+  function writeMatcherCache(key: string, value: DialMatch | null) {
+    if (matcherCache.size >= MATCHER_CACHE_MAX) {
+      const oldest = matcherCache.keys().next().value;
+      if (oldest !== undefined) 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: string,
     options: MatchLeadingDialCodeOptions = {}
@@ -158,38 +247,89 @@ export function useCountryMatching(deps: CountryMatchingDeps) {
     if (!digits) return null;
     const { hintCountry, currentIso2 } = options;
 
-    // Tier 1: international parse with leading `+`.
+    const cacheKey = `${digits}|${hintCountry ?? ''}|${currentIso2 ?? ''}`;
+    const cached = readMatcherCache(cacheKey);
+    if (cached !== undefined) return cached;
+
+    const result = runMatch(digits, hintCountry, currentIso2);
+    writeMatcherCache(cacheKey, result);
+    return result;
+  }
+
+  // Pure tier-1/2/3 matcher — extracted so the public `matchLeadingDialCode` is a thin
+  // memoisation wrapper. Returns the first match found; `null` if none.
+  function runMatch(
+    digits: string,
+    hintCountry: string | undefined,
+    currentIso2: string | undefined
+  ): DialMatch | null {
+    // Tier 1: international parse with leading `+`. libphonenumber knows every
+    // country's dial code natively — so even when our async country index hasn't
+    // populated yet (first paint, no localStorage cache), we can still return a
+    // synthetic `CountryOption` derived from the parse result and let the picker
+    // upgrade it to the real entry when the fetch resolves.
     try {
       const parsed = parsePhoneNumberFromString(`+${digits}`);
       if (parsed?.country && parsed.countryCallingCode) {
-        const parsedCountry = getCountryByValue(parsed.country);
-        if (parsedCountry) {
-          return { country: parsedCountry, nationalNumber: String(parsed.nationalNumber ?? '') };
-        }
+        const parsedCountry =
+          getCountryByValue(parsed.country) ??
+          buildSyntheticCountry(parsed.country, String(parsed.countryCallingCode));
+        return { country: parsedCountry, nationalNumber: String(parsed.nationalNumber ?? '') };
       }
     } catch {
       /* libphonenumber throws on partial input — fall through */
     }
 
-    // Tier 2: national-format parse using the silently-inferred country as a hint.
-    if (hintCountry && digits.length >= 4) {
-      try {
-        const parsed = parsePhoneNumberFromString(digits, hintCountry as CountryCode);
-        if (parsed?.isValid()) {
-          const matched = getCountryByValue(parsed.country || hintCountry);
-          if (matched) {
+    // Tier 2: national-format parse. Iterate through candidate hint countries — the env
+    // hint, the current selection, the user's recents, the popular-countries shortlist,
+    // and finally **every** ISO2 libphonenumber knows about — and return the first one
+    // that yields a valid parse. This is what lets `01066105963` resolve to Egypt even
+    // when the silent IP/timezone hint is `SA` (the SA parse rejects the number, but
+    // iterating finds EG). First-match wins, so the iteration ORDER encodes the priority:
+    //   1. Env hint (`hintCountry`).
+    //   2. Current picker selection (`currentIso2`).
+    //   3. The user's recents (most-recent first).
+    //   4. The popular-countries shortlist (`FALLBACK_ISO2_LIST`).
+    //   5. Every other libphonenumber country.
+    // Step 5 guarantees universal coverage; the earlier steps bias to the more
+    // contextually-likely answers when multiple countries would each accept the input.
+    if (digits.length >= 4) {
+      const candidates = new Set<string>();
+      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 as CountryCode);
+          if (parsed?.isValid()) {
+            const resolvedIso2 = parsed.country || iso2;
+            const matched =
+              getCountryByValue(resolvedIso2) ??
+              buildSyntheticCountry(resolvedIso2, String(parsed.countryCallingCode ?? ''));
             return { country: matched, nationalNumber: String(parsed.nationalNumber ?? '') };
           }
+        } catch {
+          /* libphonenumber throws on partial input — try next candidate */
         }
-      } catch {
-        /* fall through */
       }
     }
 
-    // Tier 3: longest-prefix match over the dial-digits index.
+    // Tier 3: longest-prefix match over the dial-digits index, with the synchronous
+    // `DIAL_TO_ISO2_FALLBACK` table (~60 countries) as a backstop when the async
+    // country index hasn't loaded yet. This keeps detection working from first paint
+    // for every country in the table — not just the ~22 in `FALLBACK_COUNTRIES`.
     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 { country: group[0], nationalNumber };

package/src/composables/useCountrySelection.ts

@@ -0,0 +1,71 @@
+import { computed, ref, type ComputedRef, type Ref } from 'vue';
+
+/**
+ * How the currently-selected country came to be.
+ *
+ * The source drives the detection state machine — some sources are "hints" that
+ * typed-international input is allowed to override (`'default'`, `'env'`,
+ * `'external'`), others are "locks" that must be cleared before detection can
+ * re-route the picker (`'picker'`, `'input'`).
+ */
+export type CountrySource =
+  /** Nothing selected. */
+  | 'none'
+  /** Seeded from the `defaultCountry` prop at mount. Overridable. */
+  | 'default'
+  /** Silent IP / timezone / `navigator.language` resolution at mount. Overridable. */
+  | 'env'
+  /** `tryMatchPhone` recognised a dial code in user input. Locks until cleared. */
+  | 'input'
+  /** User clicked an item in the country picker. Locks until cleared. */
+  | 'picker'
+  /** Caller wrote `v-model:country` (dial number) or `v-model` (E.164) directly.
+   *  Treated as a hint — typed-international input can still override. */
+  | 'external';
+
+export interface UseCountrySelectionReturn {
+  /** Currently selected ISO 3166-1 alpha-2 code, or `''` when no country selected. */
+  iso2: Ref<string>;
+  /** Where the current selection came from. */
+  source: Ref<CountrySource>;
+  /** `true` when typed-input detection should be suppressed (`'picker'` / `'input'`). */
+  detectionLocked: ComputedRef<boolean>;
+  /** Set both `iso2` and `source` atomically. The single mutator for the selection. */
+  set: (iso2: string, source: CountrySource) => void;
+  /** Reset to the empty / no-country state. */
+  clear: () => void;
+}
+
+/**
+ * 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;`.
+ */
+export function useCountrySelection(): UseCountrySelectionReturn {
+  const iso2 = ref<string>('');
+  const source = ref<CountrySource>('none');
+
+  function set(nextIso2: string, nextSource: CountrySource) {
+    iso2.value = nextIso2;
+    source.value = nextSource;
+  }
+
+  function clear() {
+    iso2.value = '';
+    source.value = 'none';
+  }
+
+  // A "locked" source means the user (or `tryMatchPhone`) has committed to this
+  // country — further typed-input detection must not churn the picker. The hint
+  // sources (`'default'`, `'env'`, `'external'`) remain overridable by an explicit
+  // typed-international prefix; the component layer applies that policy.
+  const detectionLocked = computed(() => source.value === 'picker' || source.value === 'input');
+
+  return { iso2, source, set, clear, detectionLocked };
+}

package/src/composables/usePhoneValidation.ts

@@ -94,6 +94,25 @@ export type ValidateArgs =
 const STORAGE_KEY = 'ali_ui_phone_countries_v1';
 const REST_COUNTRIES_URL = 'https://restcountries.com/v3.1/all?fields=name,cca2,idd,flags';
 
+/* -----------------------------------------------------------------------------
+ * Module-level singleton state for country data.
+ *
+ * `usePhoneValidation()` is called once per `<ATelInput>`, once per `<ACountrySelect>`,
+ * once per `useTelField()`, once per `zPhone()` — so a single page can spin up four
+ * or more instances. Without deduplication, each instance would independently:
+ *   - JSON.parse the localStorage cache,
+ *   - fire the REST Countries fetch (~80KB),
+ *   - parse + normalise the response.
+ *
+ * Sharing the result via these module-level slots collapses every concurrent call
+ * to **one** network request and **one** cache parse for the lifetime of the page.
+ * Each `usePhoneValidation()` instance still gets its own reactive `countries` ref,
+ * so consumers can mutate their local view (e.g., `props.countries` override) without
+ * affecting siblings — the singleton is only consulted as a data source.
+ * -------------------------------------------------------------------------- */
+let sharedCountries: CountryOption[] | null = null;
+let inflightFetch: Promise<CountryOption[]> | null = null;
+
 const EX = examples as unknown as Examples;
 
 const isBrowser = () => typeof window !== 'undefined';
@@ -267,10 +286,16 @@ export function usePhoneValidation(): UsePhoneValidationReturn {
   const countries = ref<CountryOption[]>([]);
   const isCountriesLoading = ref(false);
 
-  const byValue = ref<Map<string, CountryOption>>(new Map());
-  const byDialDigits = ref<Map<string, CountryOption[]>>(new Map());
-
-  function rebuildIndexes(list: CountryOption[]) {
+  // Pre-seed the lookup indexes with the bundled fallback (~22 most-populated countries).
+  // This makes country *detection* (matchLeadingDialCode, getCountryByValue) work
+  // synchronously from first paint — without it, typing a +20/+1/+44 etc. number while
+  // the REST Countries fetch is in flight would silently fail every matcher tier because
+  // `parsePhoneNumberFromString('+201066105963').country = 'EG'` can't resolve to a
+  // `CountryOption` (empty index → null) and tier 3's `getCountriesByDial('20')` also
+  // returns []. `countries.value` stays `[]` so `getCountries()` still runs its
+  // localStorage → network upgrade path; once that resolves the indexes are rebuilt
+  // wholesale with the full ~250-entry list.
+  function buildIndexes(list: CountryOption[]) {
     const valueMap = new Map<string, CountryOption>();
     const dialMap = new Map<string, CountryOption[]>();
     for (const item of list) {
@@ -282,6 +307,15 @@ export function usePhoneValidation(): UsePhoneValidationReturn {
         dialMap.set(dial, bucket);
       }
     }
+    return { valueMap, dialMap };
+  }
+
+  const _seed = buildIndexes(FALLBACK_COUNTRIES);
+  const byValue = ref<Map<string, CountryOption>>(_seed.valueMap);
+  const byDialDigits = ref<Map<string, CountryOption[]>>(_seed.dialMap);
+
+  function rebuildIndexes(list: CountryOption[]) {
+    const { valueMap, dialMap } = buildIndexes(list);
     byValue.value = valueMap;
     byDialDigits.value = dialMap;
   }
@@ -335,12 +369,33 @@ export function usePhoneValidation(): UsePhoneValidationReturn {
     const force = Boolean(options?.force);
     if (!force && countries.value.length) return countries.value;
 
+    // Shared module-level cache — if any sibling instance already loaded the list,
+    // adopt it without re-parsing localStorage or hitting the network.
+    if (!force && sharedCountries) {
+      upsertCountries(sharedCountries);
+      return countries.value;
+    }
+
+    // Shared in-flight promise — if another instance fired the fetch first, await
+    // its result instead of starting a duplicate request.
+    if (!force && inflightFetch) {
+      isCountriesLoading.value = true;
+      try {
+        const list = await inflightFetch;
+        upsertCountries(list);
+        return countries.value;
+      } finally {
+        isCountriesLoading.value = false;
+      }
+    }
+
     if (!force && isBrowser()) {
       try {
         const cached = localStorage.getItem(STORAGE_KEY);
         if (cached) {
           const parsed = JSON.parse(cached) as CountryOption[];
           if (Array.isArray(parsed) && parsed.length) {
+            sharedCountries = parsed;
             upsertCountries(parsed);
             return countries.value;
           }
@@ -351,22 +406,30 @@ export function usePhoneValidation(): UsePhoneValidationReturn {
     }
 
     isCountriesLoading.value = true;
-    try {
-      const res = await fetch(REST_COUNTRIES_URL);
-      if (!res.ok) throw new Error(`Failed to fetch countries: ${res.status}`);
-      const data = (await res.json()) as RestCountry[];
-      const normalized = normalizeRestCountries(data);
-      upsertCountries(normalized.length ? normalized : FALLBACK_COUNTRIES);
-      if (isBrowser()) {
-        try {
-          localStorage.setItem(STORAGE_KEY, JSON.stringify(countries.value));
-        } catch {
-          /* storage full or disabled */
+    inflightFetch = (async (): Promise<CountryOption[]> => {
+      try {
+        const res = await fetch(REST_COUNTRIES_URL);
+        if (!res.ok) throw new Error(`Failed to fetch countries: ${res.status}`);
+        const data = (await res.json()) as RestCountry[];
+        const normalized = normalizeRestCountries(data);
+        const list = normalized.length ? normalized : FALLBACK_COUNTRIES;
+        if (isBrowser()) {
+          try {
+            localStorage.setItem(STORAGE_KEY, JSON.stringify(list));
+          } catch {
+            /* storage full or disabled */
+          }
         }
+        return list;
+      } catch {
+        return FALLBACK_COUNTRIES;
       }
-      return countries.value;
-    } catch {
-      upsertCountries(FALLBACK_COUNTRIES);
+    })();
+
+    try {
+      const list = await inflightFetch;
+      sharedCountries = list;
+      upsertCountries(list);
       return countries.value;
     } finally {
       isCountriesLoading.value = false;

package/src/composables/useSyncedModel.ts

@@ -0,0 +1,80 @@
+import { watch, type Ref, type WatchSource } from 'vue';
+
+export interface UseSyncedModelOptions<T> {
+  /** The `defineModel` ref to keep in sync with internal state. */
+  model: Ref<T>;
+  /**
+   * Internal reactive sources that, when they change, should re-compose and emit
+   * a new model value. Typically the refs that {@link compose} reads from.
+   */
+  triggers: WatchSource[];
+  /** Compose the next model value from current internal state. */
+  compose: () => T;
+  /** Apply an externally-written model value into internal state. */
+  apply: (next: T) => void;
+  /** Equality test for the model value. Defaults to `Object.is`. */
+  isEqual?: (a: T, b: T) => boolean;
+}
+
+/**
+ * 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.
+ */
+export function useSyncedModel<T>(options: UseSyncedModelOptions<T>): void {
+  const { model, triggers, compose, apply } = options;
+  const isEqual = options.isEqual ?? Object.is;
+
+  let applying = false;
+  let lastEmitted: T | { __unset: true } = { __unset: true };
+  const isEcho = (v: T) =>
+    typeof lastEmitted === 'object' && lastEmitted !== null && '__unset' in (lastEmitted as object)
+      ? false
+      : isEqual(v, lastEmitted as T);
+
+  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' }
+  );
+}

package/src/composables/useTelInputValidation.ts

@@ -15,13 +15,15 @@ import type { TelInputMessages } from '../types';
  * component needs:
  *
  * - `validation` / `validationState` — the raw + simplified state of the current input.
- * - `visibleValidationState` — `validationState` gated by the `hasFinishedTyping` flag
- *   from {@link useTypingPhase}, so error tints / icons / messages only appear once the
- *   user has paused. This is the value the template should bind to.
+ * - `visibleValidationState` — `validationState` gated by `validateOn` + the
+ *   `hasFinishedTyping` flag from {@link useTypingPhase}, so error tints / icons /
+ *   messages only appear at the right moment (after typing pause, after blur, or eagerly).
+ *   This is the value the template should bind to.
  * - `errorMessage` — localised error string for the current `validation.reason`, or
- *   `null` when the input is empty or valid.
+ *   `null` when the input is empty / valid. When an external `error` is supplied
+ *   (e.g. from VeeValidate), it wins.
  * - `showError` / `showHint` — boolean computed properties for conditional rendering
- *   in the template; both already respect `showValidation` and the typing-pause gate.
+ *   in the template; both already respect `showValidation` and the visible-state gate.
  * - `selectedDialCode` — the human-readable dial prefix (`+20`, `+1`, …) for the
  *   selected country, used as an in-input prefix.
  *
@@ -43,6 +45,17 @@ export interface UseTelInputValidationDeps {
   getCountryByValue: UsePhoneValidationReturn['getCountryByValue'];
 }
 
+/** When to surface validation in the UI.
+ *  - `'change'` (default) — visible state mirrors the typing-paused state. Errors light up
+ *    a beat after the user stops typing. Best for inline forms.
+ *  - `'blur'` — visible state stays `'idle'` until the input has been blurred at least
+ *    once, then mirrors typing-paused state. Best for VeeValidate / form-library flows
+ *    that validate on blur.
+ *  - `'eager'` — visible state mirrors raw `validationState` immediately on every keystroke,
+ *    no typing pause. Use sparingly; can feel aggressive.
+ */
+export type ATelInputValidateOn = 'change' | 'blur' | 'eager';
+
 export interface UseTelInputValidationInputs {
   /** Digits-only national number model. */
   phone: Ref<string>;
@@ -50,6 +63,8 @@ export interface UseTelInputValidationInputs {
   selectedIso2: Ref<string>;
   /** From {@link useTypingPhase} — gates visible state during the debounce window. */
   hasFinishedTyping: Readonly<Ref<boolean>>;
+  /** Whether the input has been blurred at least once. Drives `validateOn: 'blur'`. */
+  hasBlurred: Readonly<Ref<boolean>>;
   /** Resolved i18n messages (merged defaults + consumer overrides). */
   messages: ComputedRef<TelInputMessages>;
 }
@@ -61,6 +76,15 @@ export interface UseTelInputValidationConfig {
   showValidation: () => boolean | undefined;
   /** Per-reason error string overrides. From props. */
   errorMessages: () => Partial<Record<PhoneValidationReason, string>> | undefined;
+  /** When to surface validation in the UI. Defaults to `'change'`. */
+  validateOn: () => ATelInputValidateOn | undefined;
+  /**
+   * Externally controlled error (from VeeValidate / Zod / a custom form layer). When set
+   * to a non-empty string, the component is forced into `'error'` state and surfaces this
+   * message regardless of internal validation. `null` / `undefined` / `''` defers to the
+   * internal validator.
+   */
+  externalError: () => string | null | undefined;
 }
 
 export interface UseTelInputValidationReturn {
@@ -93,25 +117,40 @@ export function useTelInputValidation(
     })
   );
 
+  const externalErrorActive = computed<boolean>(() => {
+    const e = config.externalError();
+    return typeof e === 'string' && e.length > 0;
+  });
+
   const validationState = computed<'idle' | 'valid' | 'error'>(() => {
+    if (externalErrorActive.value) return 'error';
     if (!inputs.phone.value) return 'idle';
     return validation.value.ok ? 'valid' : 'error';
   });
 
-  const visibleValidationState = computed<'idle' | 'valid' | 'error'>(() =>
-    inputs.hasFinishedTyping.value ? validationState.value : 'idle'
-  );
+  const visibleValidationState = computed<'idle' | 'valid' | 'error'>(() => {
+    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<string | null>(() => {
+    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>(() =>
-    Boolean(config.showValidation() && inputs.hasFinishedTyping.value && errorMessage.value)
-  );
+  const showError = computed<boolean>(() => {
+    if (!errorMessage.value) return false;
+    if (externalErrorActive.value) return true;
+    if (!config.showValidation()) return false;
+    return visibleValidationState.value === 'error';
+  });
 
   const showHint = computed<boolean>(
     () => !showError.value && !inputs.phone.value && !!required.value?.format_hint

package/src/index.ts

@@ -34,3 +34,5 @@ export * from './composables/useCountryDetection';
 export * from './composables/useCountryMatching';
 export * from './composables/useTypingPhase';
 export * from './composables/useTelInputValidation';
+export * from './composables/useCountrySelection';
+export * from './composables/useSyncedModel';