@alikhalilll/a-tel-input 1.0.2 → 1.1.1

package/dist/index.d.ts

@@ -1,527 +1,12 @@
-import { ComputedRef, HTMLAttributes, Ref } from "vue";
-import { VariantProps } from "class-variance-authority";
+import { A as RestCountry, C as UseTelInputValidationInputs, D as PhoneRequiredInfo, E as CountryOption, F as DetectCountryOptions, I as DetectionStrategy, L as UseCountryDetectionReturn, M as ValidateArgs, N as localizeCountries, O as PhoneValidationReason, P as usePhoneValidation, R as detectCountry, S as UseTelInputValidationDeps, T as useTelInputValidation, _ as resolveMessages, a as ACountrySelectSlots, b as ATelInputValidateOn, c as ATelInputProps, d as ATelInputVariants, f as DEFAULT_ERROR_MESSAGES, g as aTelInputVariants, h as TelInputMessagesInput, i as ACountrySelectProps, j as UsePhoneValidationReturn, k as PhoneValidationResult, l as ATelInputSize, m as TelInputMessages, n as ACountryFlagSlots, o as ATelInputDir, p as DEFAULT_MESSAGES, r as ACountrySelectEmits, s as ATelInputEmits, t as ACountryFlagProps, u as ATelInputSlots, v as FlagUrlBuilder, w as UseTelInputValidationReturn, x as UseTelInputValidationConfig, y as defaultFlagUrl, z as useCountryDetection } from "./_chunks/types.js";
+import { ComputedRef, Ref, WatchSource } from "vue";
 
-//#region src/composables/useCountryDetection.d.ts
-type DetectionStrategy = 'auto' | 'locale' | 'none';
-interface DetectCountryOptions {
-  /**
-   * - `'auto'` — try IP geolocation first, then timezone, then `navigator.language`, then default.
-   * - `'locale'` — skip the network call, use timezone + locale only.
-   * - `'none'` — return `defaultCountry` immediately.
-   */
-  strategy?: DetectionStrategy;
-  /** Endpoint returning a JSON body with a `country_code` (or `country`) field. */
-  ipEndpoint?: string;
-  /** Fallback ISO2 used when every step fails. */
-  defaultCountry?: string;
-  /** Abort the IP request after this many ms. */
-  timeoutMs?: number;
-  /** Persist the resolved country in sessionStorage so re-mounts within the session skip detection. */
-  cache?: boolean;
-}
-/**
- * Imperative API. Use this when you want to call detection from outside Vue (e.g. inside a
- * non-component composable, server middleware, or unit test).
- */
-declare function detectCountry(opts?: DetectCountryOptions): Promise<string>;
-interface UseCountryDetectionReturn {
-  /** Resolved ISO2 code. Initially `null` until detection completes. */
-  country: Ref<string | null>;
-  /** True while detection is in flight. */
-  isLoading: Ref<boolean>;
-  /** Manually re-run detection (e.g. after the user changes their VPN). */
-  refresh: () => Promise<string>;
-}
-/**
- * Reactive wrapper. Kicks off detection in `onMounted` so SSR renders an empty value and the
- * client patches in the real country once resolved.
- */
-declare function useCountryDetection(opts?: DetectCountryOptions): UseCountryDetectionReturn;
-//#endregion
-//#region src/composables/usePhoneValidation.d.ts
-interface RestCountry {
-  name?: {
-    common?: string;
-  };
-  cca2?: string;
-  idd?: {
-    root?: string;
-    suffixes?: string[];
-  };
-  flags?: {
-    png?: string;
-    svg?: string;
-  };
-}
-interface CountryOption<T = RestCountry> {
-  /** Display label, e.g. "Egypt (+20)". */
-  label: string;
-  /** Stable unique ID — the ISO 3166-1 alpha-2 code, e.g. "EG". */
-  value: string;
-  /** Precomputed normalized string for fast substring search. */
-  search_key: string;
-  raw_data: {
-    iso2: string;
-    dial_code: string;
-    dial_digits: string;
-    name: string;
-    flag: string | null;
-    source: 'restcountries' | 'fallback';
-    original: T;
-  };
-}
-interface PhoneRequiredInfo {
-  iso2: string;
-  dial_code: string;
-  /** Empty by default — consumer passes a placeholder via the component prop. */
-  placeholder: string;
-  example_national: string;
-  example_e164: string;
-  national_number_length: {
-    min: number | null;
-    max: number | null;
-  };
-  format_hint: string;
-}
-type PhoneValidationReason = 'missing_country' | 'country_not_supported' | 'phone_has_non_digits' | 'too_short' | 'too_long' | 'invalid_phone' | 'parse_failed';
-interface PhoneValidationResult {
-  ok: boolean;
-  reason: PhoneValidationReason | null;
-  country: {
-    iso2: string;
-    dial_code: string;
-  } | null;
-  phone: {
-    raw: string | null;
-    digits: string;
-  };
-  full_phone: string | null;
-  required: PhoneRequiredInfo | null;
-  details?: Record<string, unknown>;
-}
-type ValidateArgs = {
-  country: {
-    iso2: string;
-    dial_code?: string;
-  } | null | undefined;
-  phone?: undefined; /** BCP-47 locale — localizes the numerals in the returned `required.format_hint`. */
-  locale?: string;
-} | {
-  country: {
-    iso2: string;
-    dial_code?: string;
-  } | null | undefined;
-  phone: string | null; /** BCP-47 locale — localizes the numerals in the returned `required.format_hint`. */
-  locale?: string;
-};
-/**
- * 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.
- */
-declare function localizeCountries(list: CountryOption[], locale?: string): CountryOption[];
-interface UsePhoneValidationReturn {
-  countries: Ref<CountryOption[]>;
-  isCountriesLoading: Ref<boolean>;
-  getCountries(options?: {
-    force?: boolean;
-  }): Promise<CountryOption[]>;
-  searchCountries(keyword: string, limit?: number): CountryOption[];
-  getCountryByValue(value: string): CountryOption | null;
-  getCountriesByDial(dial: string): CountryOption[];
-  getRequiredInfo(country: {
-    iso2: string;
-    dial_code?: string;
-  }, locale?: string): PhoneRequiredInfo | null;
-  validate(input: ValidateArgs): PhoneValidationResult;
-}
-declare function usePhoneValidation(): UsePhoneValidationReturn;
-//#endregion
-//#region src/utils/flag-url.d.ts
-/**
- * Default flag URL builder — flagcdn.com hosts PNG flags at multiple widths and is
- * generous with caching + no API key required. Swap via the `flagUrl` prop on
- * ATelInput / ACountrySelect / ACountryFlag to use any other source.
- */
-declare function defaultFlagUrl(iso2: string, width?: number): string;
-type FlagUrlBuilder = (iso2: string, width: number) => string;
-//#endregion
-//#region ../AUiBase/dist/index.d.ts
-//#endregion
-//#region src/sizes.d.ts
-/**
- * Shared size scale for every interactive component in the @alikhalilll/a-* set.
- *
- *   xs = 28px · sm = 36px · md = 43px (default) · lg = 52px · xl = 60px
- *
- * Use the {@link controlHeight}, {@link controlPaddingX}, {@link controlTextSize}
- * maps when building a CVA variant so every component stays in lockstep.
- */
-type Size = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
-//#endregion
-//#region src/types.d.ts
-/** Alias for the shared `Size` scale — kept for backwards-friendly naming. */
-type ATelInputSize = Size;
-declare const aTelInputVariants: (props?: ({
-  size?: "xs" | "sm" | "md" | "lg" | "xl" | null | undefined;
-} & import("class-variance-authority/types").ClassProp) | undefined) => string;
-type ATelInputVariants = VariantProps<typeof aTelInputVariants>;
-/** Text direction for the field. `'auto'` (or omitting the prop) inherits from the
- *  nearest `[dir]` ancestor / `<html dir>`; `'ltr'` / `'rtl'` force it. */
-type ATelInputDir = 'ltr' | 'rtl' | 'auto';
-/**
- * Every user-facing string in the tel-input UI, bundled so a consumer can localize the
- * component in one prop. Each key has an English default in {@link DEFAULT_MESSAGES}.
- */
-interface TelInputMessages {
-  /** Placeholder of the country-picker search box. */
-  searchPlaceholder: string;
-  /** Shown when a search yields no countries. */
-  emptyText: string;
-  /** Shown while the country list is loading. */
-  loadingText: string;
-  /** Header of the "Suggested" group (current + recent picks). */
-  suggestedLabel: string;
-  /** Header of the full country list. */
-  allCountriesLabel: string;
-  /** Validation error text, keyed by reason. */
-  errorMessages: Record<PhoneValidationReason, string>;
-  /** Prefix of the country trigger's `aria-label`, e.g. `"Country: Egypt"`. */
-  countryLabel: string;
-  /** `aria-label` of the country trigger when no country is selected. */
-  selectCountryLabel: string;
-  /** `aria-label` of the phone input element. */
-  phoneInputLabel: string;
-}
-/** Partial override shape for the `messages` prop — every key (and every error reason) is optional. */
-type TelInputMessagesInput = Partial<Omit<TelInputMessages, 'errorMessages'>> & {
-  errorMessages?: Partial<Record<PhoneValidationReason, string>>;
-};
-interface ATelInputProps {
-  class?: HTMLAttributes['class'];
-  placeholder?: string;
-  disabled?: boolean;
-  loading?: boolean;
-  size?: ATelInputSize;
-  /**
-   * Text direction. Omit (or pass `'auto'`) to inherit from the page — RTL pages get an
-   * RTL field automatically. Pass `'ltr'` / `'rtl'` to force it.
-   */
-  dir?: ATelInputDir;
-  /**
-   * BCP-47 locale (e.g. `'ar'`, `'fr'`). When set, country names render localized via
-   * `Intl.DisplayNames` and the format hint uses the locale's numerals.
-   */
-  locale?: string;
-  /**
-   * Localized UI strings. A single bag covering the picker, validation errors, and a11y
-   * labels. Individual props (`searchPlaceholder`, `emptyText`, `loadingText`,
-   * `errorMessages`) take precedence over the matching `messages` key when both are set.
-   */
-  messages?: TelInputMessagesInput;
-  /**
-   * Whitelist of allowed dial-digit codes (no `+`), e.g. `['20', '966']`.
-   * Countries outside this list are still shown in the picker but rendered as disabled.
-   */
-  allowedDialCodes?: string[];
-  /** Light up the field's validation styling — coloured border + ring on the input and the
-   *  error message line below — when the number is valid / invalid. Default `false`, so the
-   *  field stays neutral and validation surfacing is left to the consumer (via the
-   *  `validation` ref exposure). */
-  showValidation?: boolean;
-  /** Show the green check / red alert icon at the end of the field. Default `false`; opt
-   *  in with `true`. Independent of `showValidation` — you can show the icon without the
-   *  coloured field, or vice versa. The slots `#valid-icon` / `#error-icon` still apply. */
-  showValidationIcon?: boolean;
-  /**
-   * Country auto-detect strategy. Defaults to `'auto'` — try IP geolocation first, then
-   * timezone, then `navigator.language`, finally `defaultCountry`.
-   */
-  detectCountry?: DetectionStrategy;
-  /**
-   * Initial country. Accepts either an ISO2 code (`'EG'`) or a dial-digit string
-   * (`'20'`, `'+20'`). When set, the picker is visible at mount with this country
-   * pre-selected — overrides the hidden-until-detected default.
-   */
-  defaultCountry?: string;
-  /** Override the IP geolocation endpoint. Must return JSON with `country_code` or `country`. */
-  ipEndpoint?: string;
-  /** Localized strings for the country picker UI. */
-  searchPlaceholder?: string;
-  emptyText?: string;
-  loadingText?: string;
-  /** Error labels keyed by reason. Each gets a sensible English default. */
-  errorMessages?: Partial<Record<PhoneValidationReason, string>>;
-  /**
-   * When true, the country picker is hidden until a leading dial code is detected in the
-   * phone input. Every keystroke runs a longest-prefix match against known dial codes; on
-   * first match the picker reveals with that country and the matched dial digits are
-   * stripped from `phone`. Skips the onMount IP/timezone/locale detection chain.
-   */
-  detectFromInput?: boolean;
-  /**
-   * Debounce window (ms) for `detectFromInput` detection. Each keystroke schedules the
-   * libphonenumber parse + lookup; bursts of typing/paste collapse into a single call.
-   * Clearing the input is not debounced — the picker hides immediately. Default 150ms.
-   */
-  detectDebounceMs?: number;
-  /** Override the flag URL builder, forwarded to ACountrySelect. */
-  flagUrl?: (iso2: string, width: number) => string;
-  /** Custom search predicate, forwarded to ACountrySelect. */
-  searcher?: (query: string, country: CountryOption) => boolean;
-  /** Provide your own country list, forwarded to ACountrySelect. */
-  countries?: CountryOption[];
-  /**
-   * Fully custom country detection. When provided, this function runs in place of the
-   * built-in chain — `detectCountry`-style options are still honored but the function
-   * receives them and is free to ignore them.
-   */
-  detector?: (options: DetectCountryOptions) => Promise<string | null | undefined>;
-  /** Forwarded to ACountrySelect: classes for the popover content surface. */
-  contentClass?: string;
-  /** Forwarded to ACountrySelect: classes for the desktop popover surface. */
-  popoverClass?: string;
-  /** Forwarded to ACountrySelect: classes for the mobile drawer surface. */
-  drawerClass?: string;
-  /** Classes for the inner phone field input element. */
-  inputClass?: string;
-  /** Classes for the outer wrapper that holds country select + input. */
-  fieldClass?: string;
-  /** Classes for the helper hint line. */
-  hintClass?: string;
-  /** Classes for the error message line. */
-  errorClass?: string;
-  /**
-   * How page scroll is blocked while the country popover is open. Defaults to `'events'`
-   * (sticky-safe document-level lock). Pass `'body'` for the legacy
-   * `body { overflow: hidden }` lock, or `'none'` to leave page scrolling alone.
-   */
-  scrollLock?: 'events' | 'body' | 'none';
-}
-/**
- * Props for {@link ACountryFlag} — the standalone flag image component. Renders a
- * `flagcdn` image for an ISO2 code with an automatic text-badge fallback when the
- * image fails to load. Surface separately so it can be used outside `ATelInput`
- * (e.g., in a custom country picker).
- */
-interface ACountryFlagProps {
-  /** ISO 3166-1 alpha-2 country code, case-insensitive. */
-  iso2: string;
-  /** Pixel width served by flagcdn. 40 is crisp at retina up to ~24px wide. */
-  width?: number;
-  /** Optional explicit URL override. When set, `iso2` / `width` / `flagUrl` are ignored. */
-  src?: string | null;
-  /** Function `(iso2, width) => string` — fully replace the URL builder. */
-  flagUrl?: FlagUrlBuilder;
-  alt?: string;
-  class?: HTMLAttributes['class'];
-}
-/**
- * Slot prop shape for {@link ACountryFlag}. The `empty` slot is rendered when no
- * flag URL is available and no ISO2 fallback can be derived.
- */
-interface ACountryFlagSlots {
-  /** Rendered when the flag URL is unavailable and no ISO2 text fallback can be derived. */
-  empty?: () => unknown;
-}
-declare const DEFAULT_ERROR_MESSAGES: Record<PhoneValidationReason, string>;
-/** English defaults for every {@link TelInputMessages} key. */
-declare const DEFAULT_MESSAGES: TelInputMessages;
-/**
- * Merge a partial `messages` override onto the English defaults. Used internally by
- * `ATelInput` to resolve a complete {@link TelInputMessages} object.
- */
-declare function resolveMessages(input?: TelInputMessagesInput): TelInputMessages;
-/**
- * Slot prop shape for {@link ATelInput}. Use to get full slot-prop type inference
- * when overriding slots in a consumer template:
- *
- *   <ATelInput #suffix="{ validationState }">…</ATelInput>
- *                     ↑ inferred as `'idle' | 'valid' | 'error'`
- *
- * Or in TypeScript code:
- *   type SuffixProps = Parameters<NonNullable<ATelInputSlots['suffix']>>[0];
- */
-interface ATelInputSlots {
-  /** Content before the country select trigger (e.g. an icon). */
-  prefix?: () => unknown;
-  /** Content between the input and the validation icons. */
-  suffix?: (props: {
-    validationState: 'idle' | 'valid' | 'error';
-    validation: PhoneValidationResult;
-  }) => unknown;
-  /** Replace the green check shown when the number validates. */
-  'valid-icon'?: () => unknown;
-  /** Replace the warning icon shown when the number fails validation. */
-  'error-icon'?: (props: {
-    reason: string;
-  }) => unknown;
-  /** Replace the dim helper line shown below the input when empty. */
-  hint?: (props: {
-    country: string;
-    formatHint: string;
-    example: string | null;
-  }) => unknown;
-  /** Replace the error message rendered when invalid. */
-  error?: (props: {
-    message: string;
-    reason: string;
-    validation: PhoneValidationResult;
-  }) => unknown;
-  /** Forwarded to ACountrySelect — replace the trigger button. */
-  trigger?: (props: {
-    selectedCountry: CountryOption | null;
-    open: boolean;
-    sizeClasses: string;
-  }) => unknown;
-  /** Forwarded to ACountrySelect — replace the chevron. */
-  chevron?: (props: {
-    open: boolean;
-  }) => unknown;
-  /** Forwarded — replace any flag rendering. */
-  flag?: (props: {
-    country: CountryOption;
-    context: 'trigger' | 'item';
-  }) => unknown;
-  /** Forwarded — replace each country list row. */
-  item?: (props: {
-    country: CountryOption;
-    selected: boolean;
-    disabled: boolean;
-    select: () => void;
-  }) => unknown;
-  /** Forwarded — section header. */
-  'group-header'?: (props: {
-    label: string;
-    group: 'suggested' | 'all';
-  }) => unknown;
-  /** Forwarded — search bar. */
-  search?: (props: {
-    value: string;
-    setValue: (v: string) => void;
-    isSearching: boolean;
-  }) => unknown;
-  loading?: () => unknown;
-  empty?: (props: {
-    query: string;
-  }) => unknown;
-  /** Replace the spinner shown in the picker slot during the debounce window. */
-  detecting?: () => unknown;
-}
-/**
- * Emit map for {@link ATelInput}. `update:phone` carries the digits-only string,
- * `update:country` carries the dial-number (not ISO2). Surface for consumers who
- * wire the events manually instead of via `v-model:phone` / `v-model:country`.
- */
-type ATelInputEmits = {
-  'update:phone': [value: string];
-  'update:country': [value: number | null];
-};
-/**
- * Props for {@link ACountrySelect} — the standalone country picker. Surface
- * separately so it can be used outside `ATelInput` with full type support.
- */
-interface ACountrySelectProps {
-  class?: HTMLAttributes['class'];
-  triggerClass?: HTMLAttributes['class'];
-  contentClass?: HTMLAttributes['class'];
-  popoverClass?: HTMLAttributes['class'];
-  drawerClass?: HTMLAttributes['class'];
-  searchPlaceholder?: string;
-  emptyText?: string;
-  loadingText?: string;
-  suggestedLabel?: string;
-  allCountriesLabel?: string;
-  /** ISO2 codes that are selectable. Others are listed but disabled. */
-  allowedDialCodes?: string[];
-  disabled?: boolean;
-  /** Drives the trigger button padding + text size. Matches ATelInput's `size`. */
-  size?: ATelInputSize;
-  /** Max items rendered under the "Suggested" header (current + recents, deduped). */
-  suggestedLimit?: number;
-  /** Cap the number of matching countries shown in search results. */
-  maxResults?: number;
-  /** Override the flag URL builder, e.g. `(iso, w) => `/flags/${iso}.svg``. */
-  flagUrl?: (iso2: string, width: number) => string;
-  /** Custom search predicate. Default: substring match on the precomputed `search_key`. */
-  searcher?: (query: string, country: CountryOption) => boolean;
-  /** Provide your own country list (bypasses the REST Countries fetch). */
-  countries?: CountryOption[];
-  /** Override the right-side kbd hints. Pass `null` to hide. */
-  kbdOpen?: string | null;
-  kbdClose?: string | null;
-  /** BCP-47 locale — country names render localized via `Intl.DisplayNames`. */
-  locale?: string;
-  /** Prefix of the trigger's `aria-label` when a country is selected, e.g. `"Country"`. */
-  countryLabel?: string;
-  /** Trigger's `aria-label` when no country is selected. */
-  selectCountryLabel?: string;
-  /** How page scroll is blocked while the popover is open. Default `'events'`. */
-  scrollLock?: 'events' | 'body' | 'none';
-}
-/**
- * Slot prop shape for {@link ACountrySelect}. Forwarded versions of these slots
- * also appear on {@link ATelInputSlots} (`trigger`, `chevron`, `flag`, `item`,
- * etc.) — keep them in sync when changing one.
- */
-interface ACountrySelectSlots {
-  /** Replace the entire country picker trigger button. */
-  trigger?: (props: {
-    selectedCountry: CountryOption | null;
-    open: boolean;
-    sizeClasses: string;
-  }) => unknown;
-  /** Replace the chevron icon. */
-  chevron?: (props: {
-    open: boolean;
-  }) => unknown;
-  /** Replace just the flag rendered in the trigger and items. */
-  flag?: (props: {
-    country: CountryOption;
-    context: 'trigger' | 'item';
-  }) => unknown;
-  /** Replace the entire search bar (input + icon + kbd). */
-  search?: (props: {
-    value: string;
-    setValue: (v: string) => void;
-    isSearching: boolean;
-  }) => unknown;
-  /** Replace the search-bar leading icon. */
-  'search-icon'?: () => unknown;
-  /** Replace the loading state. */
-  loading?: () => unknown;
-  /** Replace the empty/no-results state. */
-  empty?: (props: {
-    query: string;
-  }) => unknown;
-  /** Replace a section header. */
-  'group-header'?: (props: {
-    label: string;
-    group: 'suggested' | 'all';
-  }) => unknown;
-  /** Replace each country list row. */
-  item?: (props: {
-    country: CountryOption;
-    selected: boolean;
-    disabled: boolean;
-    select: () => void;
-  }) => unknown;
-  /** Replace just the right-side check icon for the selected row. */
-  'item-check'?: (props: {
-    country: CountryOption;
-  }) => unknown;
-}
-/**
- * Emit map for {@link ACountrySelect}. The `selected` is `v-model:selected`,
- * carrying the ISO2 code of the picked country.
- */
-type ACountrySelectEmits = {
-  'update:selected': [value: string];
-};
-//#endregion
 //#region src/components/ATelInput.vue.d.ts
 type __VLS_Props$1 = ATelInputProps;
 type __VLS_Slots$2 = ATelInputSlots;
+declare function focus(options?: FocusOptions): void;
+declare function blur(): void;
+declare function select(): void;
 type __VLS_ModelProps$1 = {
   'phone'?: string;
   /** Public `v-model:country` — the **dial number** (e.g. `20` for Egypt, `44` for the UK,
@@ -529,25 +14,54 @@ type __VLS_ModelProps$1 = {
    *  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. */
   'country'?: number | null;
+  /**
+   * 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.
+   */
+  modelValue?: string;
 };
 type __VLS_PublicProps$1 = __VLS_Props$1 & __VLS_ModelProps$1;
 declare const __VLS_base$2: import("vue").DefineComponent<__VLS_PublicProps$1, {
   validation: import("vue").ComputedRef<PhoneValidationResult>;
   required: import("vue").ComputedRef<PhoneRequiredInfo | null>;
   selectedDialCode: import("vue").ComputedRef<string | null>;
-  validationState: import("vue").ComputedRef<"idle" | "valid" | "error">;
-  visibleValidationState: import("vue").ComputedRef<"idle" | "valid" | "error">;
+  validationState: import("vue").ComputedRef<"valid" | "error" | "idle">;
+  visibleValidationState: import("vue").ComputedRef<"valid" | "error" | "idle">;
   isDetecting: Readonly<import("vue").Ref<boolean, boolean>>;
   hasFinishedTyping: Readonly<import("vue").Ref<boolean, boolean>>;
   detectionAttempted: Readonly<import("vue").Ref<boolean, boolean>>;
+  focus: typeof focus;
+  blur: typeof blur;
+  select: typeof select;
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
-  "update:phone": (value: string) => any;
-  "update:country": (value: number | null) => any;
+  blur: (event: FocusEvent) => any;
+  "update:phone": (...args: unknown[]) => any;
+  "update:country": (...args: unknown[]) => any;
+  "update:modelValue": (...args: unknown[]) => any;
+  focus: (event: FocusEvent) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_PublicProps$1> & Readonly<{
-  "onUpdate:phone"?: ((value: string) => any) | undefined;
-  "onUpdate:country"?: ((value: number | null) => any) | undefined;
+  onBlur?: ((event: FocusEvent) => any) | undefined;
+  "onUpdate:phone"?: ((...args: unknown[]) => any) | undefined;
+  "onUpdate:country"?: ((...args: unknown[]) => any) | undefined;
+  "onUpdate:modelValue"?: ((...args: unknown[]) => any) | undefined;
+  onFocus?: ((event: FocusEvent) => any) | undefined;
 }>, {
   size: ATelInputSize;
+  validateOn: ATelInputValidateOn;
   placeholder: string;
   showValidationIcon: boolean;
   detectCountry: DetectionStrategy;
@@ -581,18 +95,18 @@ declare const __VLS_base$1: import("vue").DefineComponent<__VLS_PublicProps, {
 }, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
   "onUpdate:selected"?: ((value: string) => any) | undefined;
 }>, {
+  size: ATelInputSize;
   searchPlaceholder: string;
   emptyText: string;
   loadingText: string;
   suggestedLabel: string;
   allCountriesLabel: string;
-  size: ATelInputSize;
+  countryLabel: string;
+  selectCountryLabel: string;
   suggestedLimit: number;
   maxResults: number;
   kbdOpen: string | null;
   kbdClose: string | null;
-  countryLabel: string;
-  selectCountryLabel: string;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export$1: typeof __VLS_base$1;
 declare const _default$1: typeof __VLS_export$1;
@@ -635,6 +149,12 @@ declare const DIAL_TO_ISO2_FALLBACK: Record<string, string>;
 /** 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). */
 declare 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. */
+declare const FALLBACK_ISO2_LIST: readonly string[];
 interface DialMatch {
   country: CountryOption;
   /** The national significant number — what the phone input should hold, with both the
@@ -722,70 +242,85 @@ interface UseTypingPhaseReturn {
 }
 declare function useTypingPhase(opts: UseTypingPhaseOptions): UseTypingPhaseReturn;
 //#endregion
-//#region src/composables/useTelInputValidation.d.ts
+//#region src/composables/useCountrySelection.d.ts
 /**
- * Validation surfacing facade for ATelInput.
+ * How the currently-selected country came to be.
  *
- * Wraps the raw `usePhoneValidation()` calls and produces the *view-layer* surface the
- * component needs:
+ * 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'`).
+ */
+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';
+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.
  *
- * - `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.
- * - `errorMessage` — localised error string for the current `validation.reason`, or
- *   `null` when the input is empty or valid.
- * - `showError` / `showHint` — boolean computed properties for conditional rendering
- *   in the template; both already respect `showValidation` and the typing-pause gate.
- * - `selectedDialCode` — the human-readable dial prefix (`+20`, `+1`, …) for the
- *   selected country, used as an in-input prefix.
+ * 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;`.
+ */
+declare function useCountrySelection(): UseCountrySelectionReturn;
+//#endregion
+//#region src/composables/useSyncedModel.d.ts
+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.
  *
- * Design notes:
+ * Mechanics:
  *
- * - The composable takes the `usePhoneValidation()` return value as a *dependency*
- *   rather than calling `usePhoneValidation()` itself. That function creates a fresh
- *   country index per invocation; calling it here would produce a second, empty index
- *   that never gets populated by the caller's `getCountries()` (the same bug pattern
- *   {@link useCountryMatching} avoids).
+ *   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.
  *
- * - All inputs are `Ref` / `ComputedRef` so reactivity flows correctly. Method
- *   references on the validation singleton (`validate`, `getRequiredInfo`,
- *   `getCountryByValue`) are passed verbatim — their backing state is reactive.
+ * 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.
  */
-interface UseTelInputValidationDeps {
-  validate: UsePhoneValidationReturn['validate'];
-  getRequiredInfo: UsePhoneValidationReturn['getRequiredInfo'];
-  getCountryByValue: UsePhoneValidationReturn['getCountryByValue'];
-}
-interface UseTelInputValidationInputs {
-  /** Digits-only national number model. */
-  phone: Ref<string>;
-  /** Currently selected ISO2 — empty string when no country chosen. */
-  selectedIso2: Ref<string>;
-  /** From {@link useTypingPhase} — gates visible state during the debounce window. */
-  hasFinishedTyping: Readonly<Ref<boolean>>;
-  /** Resolved i18n messages (merged defaults + consumer overrides). */
-  messages: ComputedRef<TelInputMessages>;
-}
-interface UseTelInputValidationConfig {
-  /** BCP-47 locale; affects `format_hint` numeral rendering. */
-  locale: () => string | undefined;
-  /** Light up field tinting + error message line. From props. */
-  showValidation: () => boolean | undefined;
-  /** Per-reason error string overrides. From props. */
-  errorMessages: () => Partial<Record<PhoneValidationReason, string>> | undefined;
-}
-interface UseTelInputValidationReturn {
-  validation: ComputedRef<PhoneValidationResult>;
-  required: ComputedRef<PhoneRequiredInfo | null>;
-  validationState: ComputedRef<'idle' | 'valid' | 'error'>;
-  visibleValidationState: ComputedRef<'idle' | 'valid' | 'error'>;
-  errorMessage: ComputedRef<string | null>;
-  showError: ComputedRef<boolean>;
-  showHint: ComputedRef<boolean>;
-  selectedDialCode: ComputedRef<string | null>;
-}
-declare function useTelInputValidation(deps: UseTelInputValidationDeps, inputs: UseTelInputValidationInputs, config: UseTelInputValidationConfig): UseTelInputValidationReturn;
+declare function useSyncedModel<T>(options: UseSyncedModelOptions<T>): void;
 //#endregion
-export { _default as ACountryFlag, type ACountryFlagProps, type ACountryFlagSlots, _default$1 as ACountrySelect, type ACountrySelectEmits, type ACountrySelectProps, type ACountrySelectSlots, _default$2 as ATelInput, type ATelInputDir, type ATelInputEmits, type ATelInputProps, type ATelInputSize, type ATelInputSlots, type ATelInputVariants, COUNTRY_RECENTS_KEY, CountryMatchingDeps, CountryOption, DEFAULT_ERROR_MESSAGES, DEFAULT_MESSAGES, DIAL_TO_ISO2_FALLBACK, DetectCountryOptions, DetectionStrategy, DialMatch, type FlagUrlBuilder, LOCALE_DIGIT_RANGES, MatchLeadingDialCodeOptions, PhoneRequiredInfo, PhoneValidationReason, PhoneValidationResult, RestCountry, type TelInputMessages, type TelInputMessagesInput, UseCountryDetectionReturn, UsePhoneValidationReturn, UseTelInputValidationConfig, UseTelInputValidationDeps, UseTelInputValidationInputs, UseTelInputValidationReturn, UseTypingPhaseOptions, UseTypingPhaseReturn, ValidateArgs, aTelInputVariants, defaultFlagUrl, detectCountry, localizeCountries, normalizeDigits, resolveMessages, useCountryDetection, useCountryMatching, usePhoneValidation, useTelInputValidation, useTypingPhase };
+export { _default as ACountryFlag, type ACountryFlagProps, type ACountryFlagSlots, _default$1 as ACountrySelect, type ACountrySelectEmits, type ACountrySelectProps, type ACountrySelectSlots, _default$2 as ATelInput, type ATelInputDir, type ATelInputEmits, type ATelInputProps, type ATelInputSize, type ATelInputSlots, ATelInputValidateOn, type ATelInputVariants, COUNTRY_RECENTS_KEY, CountryMatchingDeps, CountryOption, CountrySource, DEFAULT_ERROR_MESSAGES, DEFAULT_MESSAGES, DIAL_TO_ISO2_FALLBACK, DetectCountryOptions, DetectionStrategy, DialMatch, FALLBACK_ISO2_LIST, type FlagUrlBuilder, LOCALE_DIGIT_RANGES, MatchLeadingDialCodeOptions, PhoneRequiredInfo, PhoneValidationReason, PhoneValidationResult, RestCountry, type TelInputMessages, type TelInputMessagesInput, UseCountryDetectionReturn, UseCountrySelectionReturn, UsePhoneValidationReturn, UseSyncedModelOptions, UseTelInputValidationConfig, UseTelInputValidationDeps, UseTelInputValidationInputs, UseTelInputValidationReturn, UseTypingPhaseOptions, UseTypingPhaseReturn, ValidateArgs, aTelInputVariants, defaultFlagUrl, detectCountry, localizeCountries, normalizeDigits, resolveMessages, useCountryDetection, useCountryMatching, useCountrySelection, usePhoneValidation, useSyncedModel, useTelInputValidation, useTypingPhase };
 //# sourceMappingURL=index.d.ts.map