@alikhalilll/a-tel-input 1.0.1

package/dist/index.d.cts

@@ -0,0 +1,791 @@
+import { ComputedRef, HTMLAttributes, Ref } from "vue";
+import { VariantProps } from "class-variance-authority";
+
+//#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;
+type __VLS_ModelProps$1 = {
+  'phone'?: string;
+  /** 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. */
+  'country'?: number | null;
+};
+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">;
+  isDetecting: Readonly<import("vue").Ref<boolean, boolean>>;
+  hasFinishedTyping: Readonly<import("vue").Ref<boolean, boolean>>;
+  detectionAttempted: Readonly<import("vue").Ref<boolean, boolean>>;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+  "update:phone": (value: string) => any;
+  "update:country": (value: number | null) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps$1> & Readonly<{
+  "onUpdate:phone"?: ((value: string) => any) | undefined;
+  "onUpdate:country"?: ((value: number | null) => any) | undefined;
+}>, {
+  placeholder: string;
+  size: ATelInputSize;
+  showValidationIcon: boolean;
+  detectCountry: DetectionStrategy;
+  defaultCountry: string;
+  ipEndpoint: string;
+  detectFromInput: boolean;
+  detectDebounceMs: number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export$2: typeof __VLS_base$2;
+declare const _default$2: typeof __VLS_export$2;
+//#endregion
+//#region src/components/ACountrySelect.vue.d.ts
+type __VLS_Props = ACountrySelectProps;
+type __VLS_Slots$1 = ACountrySelectSlots;
+declare function selectCountry(option: CountryOption): void;
+type __VLS_ModelProps = {
+  'selected'?: string;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_base$1: import("vue").DefineComponent<__VLS_PublicProps, {
+  open: import("vue").Ref<boolean, boolean>;
+  setOpen: (v: boolean) => boolean;
+  search: import("vue").Ref<string, string>;
+  setSearch: (v: string) => string;
+  selectedCountry: import("vue").ComputedRef<CountryOption<RestCountry> | null>;
+  selectCountry: typeof selectCountry;
+  countries: import("vue").ComputedRef<CountryOption<RestCountry>[]>;
+  recents: import("vue").Ref<string[], string[]>;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+  "update:selected": (value: string) => any;
+}, 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;
+  countryLabel: string;
+  selectCountryLabel: string;
+  suggestedLimit: number;
+  maxResults: number;
+  kbdOpen: string | null;
+  kbdClose: string | null;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export$1: typeof __VLS_base$1;
+declare const _default$1: typeof __VLS_export$1;
+//#endregion
+//#region src/components/ACountryFlag.vue.d.ts
+type __VLS_Slots = ACountryFlagSlots;
+declare const __VLS_base: import("vue").DefineComponent<ACountryFlagProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<ACountryFlagProps> & Readonly<{}>, {
+  width: number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: typeof __VLS_base;
+declare const _default: typeof __VLS_export;
+//#endregion
+//#region src/utils/digits.d.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.
+ */
+declare const LOCALE_DIGIT_RANGES: {
+  name: string;
+  base: number;
+}[];
+/**
+ * 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.
+ */
+declare function normalizeDigits(input: string): string;
+//#endregion
+//#region src/composables/useCountryMatching.d.ts
+/** Synchronous dial-digit → ISO2 fallback for common countries, used when the async
+ *  REST Countries fetch hasn't populated `getCountriesByDial`'s index yet at setup. */
+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";
+interface DialMatch {
+  country: CountryOption;
+  /** The national significant number — what the phone input should hold, with both the
+   *  dial code and the national prefix (e.g. Egyptian leading `0`) stripped. */
+  nationalNumber: string;
+}
+interface MatchLeadingDialCodeOptions {
+  /** ISO2 hint for libphonenumber's national-format parse (tier 2). Typically the
+   *  IP/timezone/locale-resolved country. */
+  hintCountry?: string;
+  /** Currently selected ISO2 — preferred when a shared dial code yields multiple
+   *  countries (tier 3 tie-break). */
+  currentIso2?: string;
+}
+interface CountryMatchingDeps {
+  /** Country lookup by ISO2 code — typically `usePhoneValidation().getCountryByValue`. */
+  getCountryByValue: (value: string) => CountryOption | null;
+  /** Country lookup by dial digits — typically `usePhoneValidation().getCountriesByDial`. */
+  getCountriesByDial: (dial: string) => CountryOption[];
+}
+/**
+ * Country-matching helpers used by the tel input — pure functions on top of the
+ * `usePhoneValidation` country index. Split out of `ATelInput.vue` so the component
+ * script stays focused on UI state and the matching logic is independently testable.
+ *
+ * **Important**: takes the validation lookups as dependencies rather than calling
+ * `usePhoneValidation()` itself. `usePhoneValidation` creates a fresh state on every
+ * call, so calling it here would produce a *second* empty country index that never gets
+ * populated by the caller's `getCountries()` — the matcher would see no countries and
+ * all tier-3 prefix lookups would fall through to the (much smaller) fallback table.
+ */
+declare function useCountryMatching(deps: CountryMatchingDeps): {
+  resolveCountryIdentifier: (raw: string | undefined | null) => string;
+  dialNumberFor: (iso2: string) => number | null;
+  matchLeadingDialCode: (digits: string, options?: MatchLeadingDialCodeOptions) => DialMatch | null;
+};
+//#endregion
+//#region src/composables/useTypingPhase.d.ts
+/**
+ * Typing-phase state machine for the tel input.
+ *
+ * Owns the three reactive flags that drive the "is the user still typing?" UX:
+ *
+ * - `isDetecting` — true while the debounce window is in flight (user is mid-burst or
+ *   has just paused). Drives the loading spinner in the picker slot.
+ * - `hasFinishedTyping` — false from the moment a key lands until the debounce settles.
+ *   Gates validation visibility, so error/success states only appear once the user pauses.
+ * - `detectionAttempted` — flips true the first time the debounce fires on non-empty
+ *   input. Used by the consumer to keep the country picker visible after a failed
+ *   detection (so the user can pick manually instead of being stranded).
+ *
+ * Design notes:
+ *
+ * - The composable is pure state — it does not know about country detection, phone
+ *   numbers, or libphonenumber. The consumer wires the `onSettle` callback to whatever
+ *   "what to do when typing pauses" logic is appropriate (typically: try to detect a
+ *   country from the current digits, mark a detection attempt, and apply the match).
+ *
+ * - `markDetectionAttempt()` is exposed separately so the caller controls *when* the
+ *   "keep the picker visible" flag flips — not every settle triggers a real attempt
+ *   (e.g. when input is empty or the user already picked a country manually).
+ *
+ * - Refs are exposed `readonly` so external code can't bypass the state machine; all
+ *   transitions go through the exposed actions.
+ */
+interface UseTypingPhaseOptions {
+  /** Debounce window in ms. Reactive so consumers can change `detectDebounceMs` at runtime. */
+  debounceMs: ComputedRef<number>;
+  /** Fired when the debounce timer settles. Runs regardless of input state — use this
+   *  to clear loading UI, then perform any pause-triggered work (e.g. detection). */
+  onSettle?: () => void;
+}
+interface UseTypingPhaseReturn {
+  isDetecting: Readonly<Ref<boolean>>;
+  hasFinishedTyping: Readonly<Ref<boolean>>;
+  detectionAttempted: Readonly<Ref<boolean>>;
+  /** Call from the input handler on every keystroke that produces non-empty input. */
+  markTyping: () => void;
+  /** Flip `detectionAttempted` to true. Call from within the `onSettle` callback when
+   *  a real detection attempt is about to run — so the picker stays visible after even
+   *  a failed match. */
+  markDetectionAttempt: () => void;
+  /** Reset all three flags to defaults. Call when the input is cleared. */
+  reset: () => void;
+}
+declare function useTypingPhase(opts: UseTypingPhaseOptions): UseTypingPhaseReturn;
+//#endregion
+//#region src/composables/useTelInputValidation.d.ts
+/**
+ * Validation surfacing facade for ATelInput.
+ *
+ * Wraps the raw `usePhoneValidation()` calls and produces the *view-layer* surface the
+ * 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.
+ * - `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.
+ *
+ * Design notes:
+ *
+ * - 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).
+ *
+ * - 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.
+ */
+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;
+//#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 };
+//# sourceMappingURL=index.d.cts.map