intl-tel-input 28.1.0 → 29.0.1

package/dist/js/intlTelInput.mjs

@@ -1752,8 +1752,8 @@ var data_default = allCountries;
 
 // packages/core/src/js/constants.ts
 var EVENTS = {
-  OPEN_COUNTRY_DROPDOWN: "open:countrydropdown",
-  CLOSE_COUNTRY_DROPDOWN: "close:countrydropdown",
+  OPEN_COUNTRY_SELECTOR: "open:countryselector",
+  CLOSE_COUNTRY_SELECTOR: "close:countryselector",
   COUNTRY_CHANGE: "countrychange",
   INPUT: "input",
   // used for synthetic input trigger
@@ -1800,9 +1800,9 @@ var TIMINGS = {
 var LAYOUT = {
   NARROW_VIEWPORT_WIDTH: 500,
   // keep in sync with .iti__country-list CSS media query
-  FALLBACK_SELECTED_WITH_DIAL_WIDTH: 78,
+  FALLBACK_SELECTED_COUNTRY_WITH_DIAL_WIDTH: 78,
   // px width fallback when separateDialCode enabled
-  FALLBACK_SELECTED_NO_DIAL_WIDTH: 42,
+  FALLBACK_SELECTED_COUNTRY_NO_DIAL_WIDTH: 42,
   // px width fallback when no separate dial code
   INPUT_PADDING_EXTRA_LEFT: 6,
   // px gap between selected country container and input text
@@ -1830,14 +1830,17 @@ var US = {
   DIAL_CODE: "1"
   // +1 United States
 };
-var PLACEHOLDER_MODES = {
-  AGGRESSIVE: "aggressive",
-  POLITE: "polite",
-  OFF: "off"
-};
-var INITIAL_COUNTRY = {
-  AUTO: "auto"
+var PLACEHOLDER_POLICY = {
+  AGGRESSIVE: "AGGRESSIVE",
+  POLITE: "POLITE",
+  OFF: "OFF"
 };
+var COUNTRY_SELECTOR_MODES = [
+  "OFF",
+  "DROPDOWN",
+  "FULLSCREEN",
+  "AUTO"
+];
 var NUMBER_FORMATS = [
   "E164",
   "INTERNATIONAL",
@@ -1870,8 +1873,9 @@ var toEnumObject = (arr) => Object.fromEntries(arr.map((v) => [v, v]));
 var NUMBER_FORMAT = toEnumObject(NUMBER_FORMATS);
 var NUMBER_TYPE = toEnumObject(NUMBER_TYPES);
 var VALIDATION_ERROR = toEnumObject(VALIDATION_ERRORS);
+var COUNTRY_SELECTOR_MODE = toEnumObject(COUNTRY_SELECTOR_MODES);
 var DATA_KEYS = {
-  // e.g. <li data-iso2="us"> for country items in dropdown
+  // e.g. <li data-iso2="us"> for country items in the country list
   ISO2: "iso2",
   DIAL_CODE: "dialCode",
   // e.g. <input data-intl-tel-input-id="0"> on the input element
@@ -1889,7 +1893,7 @@ var ARIA = {
   MODAL: "aria-modal"
 };
 
-// packages/core/src/js/i18n/en.ts
+// packages/core/src/js/locale/en.ts
 var interfaceTranslations = {
   selectedCountryAriaLabel: "Change country for phone number, currently selected ${countryName} (${dialCode})",
   noCountrySelected: "Select country for phone number",
@@ -1912,63 +1916,63 @@ var en_default = interfaceTranslations;
 // packages/core/src/js/core/options.ts
 var mediaQuery = (q) => typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia(q).matches;
 var isNarrowViewport = () => mediaQuery(`(max-width: ${LAYOUT.NARROW_VIEWPORT_WIDTH}px)`);
-var computeDefaultUseFullscreenPopup = () => {
+var resolveAutoCountrySelectorMode = () => {
   if (typeof navigator !== "undefined" && typeof window !== "undefined") {
     const isShortViewport = mediaQuery("(max-height: 600px)");
     const isCoarsePointer = mediaQuery("(pointer: coarse)");
-    return isNarrowViewport() || isCoarsePointer && isShortViewport;
+    if (isNarrowViewport() || isCoarsePointer && isShortViewport) {
+      return COUNTRY_SELECTOR_MODE.FULLSCREEN;
+    }
   }
-  return false;
+  return COUNTRY_SELECTOR_MODE.DROPDOWN;
 };
 var defaults = {
-  //* Whether or not to allow the dropdown.
-  allowDropdown: true,
+  //* How the country selector is displayed. "DROPDOWN" vs "FULLSCREEN", or "AUTO" to decide itself, or "OFF".
+  countrySelectorMode: COUNTRY_SELECTOR_MODE.AUTO,
   //* The number type to enforce during validation.
   allowedNumberTypes: [NUMBER_TYPE.MOBILE, NUMBER_TYPE.FIXED_LINE],
   //* Whether or not to allow extensions after the main number.
   allowNumberExtensions: false,
   // Allow alphanumeric "phonewords" (e.g. +1 800 FLOWERS) as valid numbers
   allowPhonewords: false,
-  //* Add a placeholder in the input with an example number for the selected country.
-  autoPlaceholder: PLACEHOLDER_MODES.POLITE,
   //* Add a custom class to the (injected) container element.
   containerClass: "",
   //* Locale for localising country names via Intl.DisplayNames.
   countryNameLocale: "en",
   //* Override individual country names by iso2 code.
   countryNameOverrides: {},
-  //* The order of the countries in the dropdown. Defaults to alphabetical.
+  //* The order of the countries in the country list. Defaults to alphabetical.
   countryOrder: null,
-  //* Add a country search input at the top of the dropdown.
+  //* Add a country search input at the top of the country selector.
   countrySearch: true,
   //* Modify the auto placeholder.
   customPlaceholder: null,
   //* Always show the dropdown
   dropdownAlwaysOpen: false,
-  //* Append menu to specified element.
-  dropdownContainer: null,
+  //* Optional DOM element to append the dropdown to (used to escape ancestors with overflow:hidden, or to mount in a custom container). Only consulted in dropdown rendering; ignored when the country selector renders as a fullscreen popup.
+  dropdownParent: null,
   //* Don't display these countries.
   excludeCountries: null,
   //* Fix the dropdown width to the input width (rather than being as wide as the longest country name).
-  fixDropdownWidth: true,
+  matchDropdownWidth: true,
   //* Format the number as the user types
   formatAsYouType: true,
-  //* Format the input value during initialisation and on setNumber.
-  formatOnDisplay: true,
-  //* geoIp lookup function.
-  geoIpLookup: null,
-  //* Inject a hidden input with the name returned from this function, and on submit, populate it with the result of getNumber.
-  hiddenInput: null,
-  //* Internationalise the core library text e.g. search input placeholder, country names.
-  i18n: {},
+  //* Inject hidden inputs with the names returned from this function, and on submit, populate them with the full number and selected country iso2.
+  hiddenInputs: null,
+  //* Translations for the core library UI strings e.g. search input placeholder, country names.
+  uiTranslations: {},
   //* Initial country.
   initialCountry: "",
+  //* Async lookup function used to determine the initial country (e.g. via IP). Ignored if initialCountry is set.
+  initialCountryLookup: null,
   //* A function to load the utils script.
   loadUtils: null,
-  //* National vs international formatting for numbers e.g. placeholders and displaying existing numbers.
-  nationalMode: false,
+  //* Format used when displaying numbers (placeholder examples and stored values). One of "E164", "INTERNATIONAL", "NATIONAL".
+  numberDisplayFormat: NUMBER_FORMAT.INTERNATIONAL,
   //* Display only these countries.
   onlyCountries: null,
+  //* When to set the placeholder to an example number for the selected country: "POLITE" only when the input has no manually-set placeholder, "AGGRESSIVE" always, "OFF" never.
+  placeholderNumberPolicy: PLACEHOLDER_POLICY.POLITE,
   //* Number type to use for placeholders.
   placeholderNumberType: NUMBER_TYPE.MOBILE,
   //* Add custom classes to the search input element.
@@ -1977,12 +1981,10 @@ var defaults = {
   separateDialCode: true,
   //* When strictMode rejects a key (etc), play a short feedback animation
   strictRejectAnimation: true,
-  //* Show flags - for both the selected country, and in the country dropdown
+  //* Show flags - for both the selected country, and in the country list
   showFlags: true,
   //* Only allow certain chars e.g. a plus followed by numeric digits, and cap at max valid length.
-  strictMode: true,
-  //* Use full screen popup instead of dropdown for country list.
-  useFullscreenPopup: computeDefaultUseFullscreenPopup()
+  strictMode: true
 };
 var toString = (val) => JSON.stringify(val);
 var isPlainObject = (val) => Boolean(val) && typeof val === "object" && !Array.isArray(val);
@@ -1994,7 +1996,7 @@ var isElLike = (val) => {
   const v = val;
   return v.nodeType === 1 && typeof v.tagName === "string" && typeof v.appendChild === "function";
 };
-var placeholderModeSet = new Set(Object.values(PLACEHOLDER_MODES));
+var placeholderPolicySet = new Set(Object.values(PLACEHOLDER_POLICY));
 var warn = (message) => {
   console.warn(`[intl-tel-input] ${message}`);
 };
@@ -2040,30 +2042,48 @@ var validateOptions = (customOptions) => {
       continue;
     }
     switch (key) {
-      case "allowDropdown":
       case "allowNumberExtensions":
       case "allowPhonewords":
       case "countrySearch":
       case "dropdownAlwaysOpen":
-      case "fixDropdownWidth":
+      case "matchDropdownWidth":
       case "formatAsYouType":
-      case "formatOnDisplay":
-      case "nationalMode":
       case "showFlags":
       case "separateDialCode":
       case "strictMode":
       case "strictRejectAnimation":
-      case "useFullscreenPopup":
         if (typeof value !== "boolean") {
           warnOption(key, "a boolean", value);
           break;
         }
         validatedOptions[key] = value;
         break;
-      case "autoPlaceholder":
-        if (typeof value !== "string" || !placeholderModeSet.has(value)) {
-          const validModes = Array.from(placeholderModeSet).join(", ");
-          warnOption("autoPlaceholder", `one of ${validModes}`, value);
+      case "countrySelectorMode":
+        if (typeof value !== "string" || !COUNTRY_SELECTOR_MODES.includes(value)) {
+          warnOption(
+            "countrySelectorMode",
+            `one of ${COUNTRY_SELECTOR_MODES.map((m) => `"${m}"`).join(", ")}`,
+            value
+          );
+          break;
+        }
+        validatedOptions[key] = value;
+        break;
+      case "numberDisplayFormat":
+        if (typeof value !== "string" || value === NUMBER_FORMAT.RFC3966 || !(value === NUMBER_FORMAT.E164 || value === NUMBER_FORMAT.INTERNATIONAL || value === NUMBER_FORMAT.NATIONAL)) {
+          warnOption(
+            "numberDisplayFormat",
+            'one of "E164", "INTERNATIONAL", "NATIONAL"',
+            value
+          );
+          break;
+        }
+        validatedOptions[key] = value;
+        break;
+      case "placeholderNumberPolicy":
+        if (typeof value !== "string" || !placeholderPolicySet.has(value)) {
+          const validPolicies = Array.from(placeholderPolicySet).join(", ");
+          warnOption("placeholderNumberPolicy", `one of ${validPolicies}`, value);
           break;
         }
         validatedOptions[key] = value;
@@ -2089,8 +2109,8 @@ var validateOptions = (customOptions) => {
         break;
       }
       case "customPlaceholder":
-      case "geoIpLookup":
-      case "hiddenInput":
+      case "hiddenInputs":
+      case "initialCountryLookup":
       case "loadUtils":
         if (value !== null && !isFunction(value)) {
           warnOption(key, "a function or null", value);
@@ -2098,9 +2118,9 @@ var validateOptions = (customOptions) => {
         }
         validatedOptions[key] = value;
         break;
-      case "dropdownContainer":
+      case "dropdownParent":
         if (value !== null && !isElLike(value)) {
-          warnOption("dropdownContainer", "an HTMLElement or null", value);
+          warnOption("dropdownParent", "an HTMLElement or null", value);
           break;
         }
         validatedOptions[key] = value;
@@ -2117,9 +2137,9 @@ var validateOptions = (customOptions) => {
         }
         break;
       }
-      case "i18n":
+      case "uiTranslations":
         if (value && !isPlainObject(value)) {
-          warnOption("i18n", "an object", value);
+          warnOption("uiTranslations", "an object", value);
           break;
         }
         validatedOptions[key] = value;
@@ -2137,12 +2157,8 @@ var validateOptions = (customOptions) => {
           break;
         }
         const lower = value.toLowerCase();
-        if (lower && lower !== INITIAL_COUNTRY.AUTO && !isIso2(lower)) {
-          warnOption(
-            "initialCountry",
-            "a valid iso2 country code or 'auto'",
-            value
-          );
+        if (lower && !isIso2(lower)) {
+          warnOption("initialCountry", "a valid iso2 country code", value);
           break;
         }
         validatedOptions[key] = value;
@@ -2205,30 +2221,29 @@ var normaliseOptions = (o) => {
   }
 };
 var applyOptionSideEffects = (o) => {
+  if (o.countrySelectorMode === COUNTRY_SELECTOR_MODE.AUTO) {
+    o.countrySelectorMode = resolveAutoCountrySelectorMode();
+  }
   if (o.dropdownAlwaysOpen) {
-    o.useFullscreenPopup = false;
-    o.allowDropdown = true;
+    o.countrySelectorMode = COUNTRY_SELECTOR_MODE.DROPDOWN;
   }
-  if (o.useFullscreenPopup) {
-    o.fixDropdownWidth = false;
+  if (o.countrySelectorMode === COUNTRY_SELECTOR_MODE.FULLSCREEN) {
+    o.matchDropdownWidth = false;
   } else {
     if (isNarrowViewport()) {
-      o.fixDropdownWidth = true;
+      o.matchDropdownWidth = true;
     }
   }
   if (o.onlyCountries?.length === 1) {
     o.initialCountry = o.onlyCountries[0];
   }
-  if (o.separateDialCode) {
-    o.nationalMode = false;
-  }
-  if (o.allowDropdown && !o.showFlags && !o.separateDialCode) {
-    o.nationalMode = false;
+  if (o.separateDialCode && o.numberDisplayFormat === NUMBER_FORMAT.NATIONAL) {
+    o.numberDisplayFormat = NUMBER_FORMAT.INTERNATIONAL;
   }
-  if (o.useFullscreenPopup && !o.dropdownContainer) {
-    o.dropdownContainer = document.body;
+  if (o.countrySelectorMode !== COUNTRY_SELECTOR_MODE.OFF && !o.showFlags && !o.separateDialCode && o.numberDisplayFormat === NUMBER_FORMAT.NATIONAL) {
+    o.numberDisplayFormat = NUMBER_FORMAT.INTERNATIONAL;
   }
-  o.i18n = { ...en_default, ...o.i18n };
+  o.uiTranslations = { ...en_default, ...o.uiTranslations };
 };
 
 // packages/core/src/js/helpers/string.ts
@@ -2439,6 +2454,7 @@ var Numerals = class _Numerals {
 };
 
 // packages/core/src/js/core/ui.ts
+var supportsCssAnchor = typeof CSS !== "undefined" && typeof CSS.supports === "function" && CSS.supports("anchor-name: --x");
 var UI = class _UI {
   // private
   #options;
@@ -2453,8 +2469,8 @@ var UI = class _UI {
   #selectedCountryEl;
   #selectedFlagEl;
   #selectedDialCodeEl;
-  #dropdownArrowEl;
-  #dropdownContentEl;
+  #arrowEl;
+  #countrySelectorEl;
   #searchIconEl;
   #searchInputEl;
   #searchClearButtonEl;
@@ -2463,11 +2479,11 @@ var UI = class _UI {
   #hiddenInputCountryEl;
   #noResultsMessageEl;
   #searchResultsLiveRegionEl;
-  #detachedDropdownEl;
+  #detachedCountrySelectorEl;
   #selectedListItemEl = null;
   #highlightedListItemEl = null;
   #listItemByIso2 = /* @__PURE__ */ new Map();
-  #dropdownAbortController = null;
+  #countrySelectorAbortController = null;
   #resizeObserver;
   // public
   telInputEl;
@@ -2492,7 +2508,7 @@ var UI = class _UI {
       );
     }
   }
-  //* Generate all of the markup for the core library: the selected country overlay, and the dropdown.
+  //* Generate all of the markup for the core library: the selected country overlay, and the country selector.
   buildMarkup(countries, searchTokens) {
     this.#countries = countries;
     this.#searchTokens = searchTokens;
@@ -2515,13 +2531,13 @@ var UI = class _UI {
     this.ensureDropdownWidthSet();
   }
   #createWrapperAndInsert() {
-    const { allowDropdown, showFlags, containerClass, useFullscreenPopup } = this.#options;
+    const { countrySelectorMode, showFlags, containerClass } = this.#options;
     const parentClasses = buildClassNames({
       iti: true,
       "iti--input-container": true,
-      "iti--allow-dropdown": allowDropdown,
+      "iti--has-country-selector": countrySelectorMode !== COUNTRY_SELECTOR_MODE.OFF,
       "iti--show-flags": showFlags,
-      "iti--inline-dropdown": !useFullscreenPopup,
+      "iti--inline-country-selector": countrySelectorMode !== COUNTRY_SELECTOR_MODE.FULLSCREEN,
       [containerClass]: Boolean(containerClass)
     });
     const wrapper = createEl("div", { class: parentClasses });
@@ -2532,8 +2548,9 @@ var UI = class _UI {
     return wrapper;
   }
   #buildCountryContainer(wrapper) {
-    const { allowDropdown, separateDialCode, showFlags } = this.#options;
-    if (!allowDropdown && !showFlags && !separateDialCode) {
+    const { countrySelectorMode, separateDialCode, showFlags } = this.#options;
+    const enableCountrySelector = countrySelectorMode !== COUNTRY_SELECTOR_MODE.OFF;
+    if (!enableCountrySelector && !showFlags && !separateDialCode) {
       return;
     }
     this.#countryContainerEl = createEl(
@@ -2542,16 +2559,16 @@ var UI = class _UI {
       { class: `iti__country-container ${CLASSES.V_HIDE}` },
       wrapper
     );
-    if (allowDropdown) {
+    if (enableCountrySelector) {
       this.#selectedCountryEl = createEl(
         "button",
         {
           type: "button",
           class: "iti__selected-country",
           [ARIA.EXPANDED]: "false",
-          [ARIA.LABEL]: this.#options.i18n.noCountrySelected,
+          [ARIA.LABEL]: this.#options.uiTranslations.noCountrySelected,
           [ARIA.HASPOPUP]: "dialog",
-          [ARIA.CONTROLS]: `iti-${this.#id}__dropdown-content`
+          [ARIA.CONTROLS]: `iti-${this.#id}__country-selector`
         },
         this.#countryContainerEl
       );
@@ -2575,8 +2592,8 @@ var UI = class _UI {
       { class: CLASSES.FLAG },
       selectedCountryPrimary
     );
-    if (allowDropdown) {
-      this.#dropdownArrowEl = createEl(
+    if (enableCountrySelector) {
+      this.#arrowEl = createEl(
         "div",
         { class: "iti__arrow", [ARIA.HIDDEN]: "true" },
         selectedCountryPrimary
@@ -2589,38 +2606,39 @@ var UI = class _UI {
         this.#selectedCountryEl
       );
     }
-    if (allowDropdown) {
-      this.#buildDropdownContent();
+    if (enableCountrySelector) {
+      this.#buildCountrySelector();
     }
   }
   ensureDropdownWidthSet() {
-    const { fixDropdownWidth, allowDropdown } = this.#options;
-    if (!allowDropdown || !fixDropdownWidth || this.#dropdownContentEl.style.width) {
+    const { matchDropdownWidth, countrySelectorMode } = this.#options;
+    if (countrySelectorMode === COUNTRY_SELECTOR_MODE.OFF || !matchDropdownWidth || this.#countrySelectorEl.style.width) {
       return;
     }
     const inputWidth = this.telInputEl.offsetWidth;
     if (inputWidth > 0) {
-      this.#dropdownContentEl.style.width = `${inputWidth}px`;
+      this.#countrySelectorEl.style.width = `${inputWidth}px`;
     }
   }
-  #buildDropdownContent() {
+  #buildCountrySelector() {
     const {
-      fixDropdownWidth,
-      useFullscreenPopup,
+      matchDropdownWidth,
+      countrySelectorMode,
       countrySearch,
-      i18n,
-      dropdownContainer,
+      uiTranslations,
       containerClass
     } = this.#options;
-    const extraClasses = fixDropdownWidth ? "" : "iti--flexible-dropdown-width";
-    this.#dropdownContentEl = createEl("div", {
-      id: `iti-${this.#id}__dropdown-content`,
-      class: `iti__dropdown-content ${CLASSES.HIDE} ${extraClasses}`,
+    const isFullscreen = countrySelectorMode === COUNTRY_SELECTOR_MODE.FULLSCREEN;
+    const detachedParent = this.#getDetachedParent();
+    const extraClasses = matchDropdownWidth ? "" : "iti--flexible-dropdown-width";
+    this.#countrySelectorEl = createEl("div", {
+      id: `iti-${this.#id}__country-selector`,
+      class: `iti__country-selector ${CLASSES.HIDE} ${extraClasses}`,
       role: "dialog",
       [ARIA.MODAL]: "true"
     });
     if (this.#isRTL) {
-      this.#dropdownContentEl.setAttribute("dir", "rtl");
+      this.#countrySelectorEl.setAttribute("dir", "rtl");
     }
     if (countrySearch) {
       this.#buildSearchUI();
@@ -2631,40 +2649,54 @@ var UI = class _UI {
         class: "iti__country-list",
         id: `iti-${this.#id}__country-listbox`,
         role: "listbox",
-        [ARIA.LABEL]: i18n.countryListAriaLabel
+        [ARIA.LABEL]: uiTranslations.countryListAriaLabel
       },
-      this.#dropdownContentEl
+      this.#countrySelectorEl
     );
     this.#appendListItems();
     if (countrySearch) {
       this.#updateSearchResultsA11yText();
     }
-    if (!useFullscreenPopup) {
+    if (!isFullscreen) {
       this.#inlineDropdownHeight = this.#getHiddenInlineDropdownHeight();
       if (countrySearch) {
-        this.#dropdownContentEl.style.height = `${this.#inlineDropdownHeight}px`;
+        this.#countrySelectorEl.style.height = `${this.#inlineDropdownHeight}px`;
       }
     }
-    if (dropdownContainer) {
-      const dropdownClasses = buildClassNames({
+    if (detachedParent) {
+      const wrapperClasses = buildClassNames({
         iti: true,
-        "iti--container": true,
-        "iti--fullscreen-popup": useFullscreenPopup,
-        "iti--inline-dropdown": !useFullscreenPopup,
+        "iti--detached-country-selector": true,
+        "iti--fullscreen-popup": isFullscreen,
+        "iti--inline-country-selector": !isFullscreen,
         [containerClass]: Boolean(containerClass)
       });
-      this.#detachedDropdownEl = createEl("div", { class: dropdownClasses });
-      this.#detachedDropdownEl.appendChild(this.#dropdownContentEl);
+      this.#detachedCountrySelectorEl = createEl("div", { class: wrapperClasses });
+      this.#detachedCountrySelectorEl.appendChild(this.#countrySelectorEl);
+      if (!isFullscreen) {
+        this.#setupCssAnchorPositioning();
+      }
     } else {
-      this.#countryContainerEl.appendChild(this.#dropdownContentEl);
+      this.#countryContainerEl.appendChild(this.#countrySelectorEl);
+    }
+  }
+  //* Resolve the DOM element to attach the country selector to. Fullscreen always uses document.body; dropdown uses the consumer-supplied dropdownParent (if any); otherwise the country selector renders inline within the input wrapper (no detached element).
+  #getDetachedParent() {
+    const { countrySelectorMode, dropdownParent } = this.#options;
+    if (countrySelectorMode === COUNTRY_SELECTOR_MODE.FULLSCREEN) {
+      return document.body;
     }
+    if (countrySelectorMode === COUNTRY_SELECTOR_MODE.DROPDOWN) {
+      return dropdownParent;
+    }
+    return null;
   }
   #buildSearchUI() {
-    const { i18n, searchInputClass } = this.#options;
+    const { uiTranslations, searchInputClass } = this.#options;
     const searchWrapper = createEl(
       "div",
       { class: "iti__search-input-wrapper" },
-      this.#dropdownContentEl
+      this.#countrySelectorEl
     );
     this.#searchIconEl = createEl(
       "span",
@@ -2682,11 +2714,11 @@ var UI = class _UI {
         // Chrome says inputs need either a name or an id
         type: "search",
         class: `iti__search-input ${searchInputClass}`,
-        placeholder: i18n.searchPlaceholder,
+        placeholder: uiTranslations.searchPlaceholder,
         // role=combobox + aria-autocomplete=list + aria-activedescendant allows maintaining focus on the search input while allowing users to navigate search results with up/down keyboard keys
         role: "combobox",
         [ARIA.EXPANDED]: "true",
-        [ARIA.LABEL]: i18n.searchPlaceholder,
+        [ARIA.LABEL]: uiTranslations.searchPlaceholder,
         [ARIA.CONTROLS]: `iti-${this.#id}__country-listbox`,
         [ARIA.AUTOCOMPLETE]: "list",
         autocomplete: "off"
@@ -2698,7 +2730,7 @@ var UI = class _UI {
       {
         type: "button",
         class: `iti__search-clear ${CLASSES.HIDE}`,
-        [ARIA.LABEL]: i18n.clearSearchAriaLabel,
+        [ARIA.LABEL]: uiTranslations.clearSearchAriaLabel,
         tabindex: "-1"
       },
       searchWrapper
@@ -2707,7 +2739,7 @@ var UI = class _UI {
     this.#searchResultsLiveRegionEl = createEl(
       "span",
       { class: "iti__a11y-text" },
-      this.#dropdownContentEl
+      this.#countrySelectorEl
     );
     this.#noResultsMessageEl = createEl(
       "div",
@@ -2716,9 +2748,9 @@ var UI = class _UI {
         [ARIA.HIDDEN]: "true"
         // all a11y messaging happens in this.#searchResultsLiveRegionEl
       },
-      this.#dropdownContentEl
+      this.#countrySelectorEl
     );
-    this.#noResultsMessageEl.textContent = i18n.searchEmptyState ?? null;
+    this.#noResultsMessageEl.textContent = uiTranslations.searchEmptyState ?? null;
   }
   #updateInputPaddingAndReveal() {
     if (!this.#countryContainerEl) {
@@ -2728,12 +2760,12 @@ var UI = class _UI {
     this.#countryContainerEl.classList.remove(CLASSES.V_HIDE);
   }
   #buildHiddenInputs(wrapper) {
-    const { hiddenInput } = this.#options;
-    if (!hiddenInput) {
+    const { hiddenInputs } = this.#options;
+    if (!hiddenInputs) {
       return;
     }
     const telInputName = this.telInputEl.getAttribute("name") || "";
-    const names = hiddenInput(telInputName);
+    const names = hiddenInputs(telInputName);
     if (names.phone) {
       const existingInput = this.telInputEl.form?.querySelector(
         `input[name="${names.phone}"]`
@@ -2798,7 +2830,7 @@ var UI = class _UI {
   //* Update the input padding to make space for (1) the selected country/globe, (2) the arrow, and (3) the separate dial code, all of which are optional, hence handling this in the JS rather than CSS.
   #updateInputPadding() {
     if (this.#selectedCountryEl) {
-      const fallbackWidth = this.#options.separateDialCode ? LAYOUT.FALLBACK_SELECTED_WITH_DIAL_WIDTH : LAYOUT.FALLBACK_SELECTED_NO_DIAL_WIDTH;
+      const fallbackWidth = this.#options.separateDialCode ? LAYOUT.FALLBACK_SELECTED_COUNTRY_WITH_DIAL_WIDTH : LAYOUT.FALLBACK_SELECTED_COUNTRY_NO_DIAL_WIDTH;
       const selectedCountryWidth = this.#selectedCountryEl.offsetWidth || this.#getHiddenSelectedCountryWidth() || fallbackWidth;
       const inputPadding = selectedCountryWidth + LAYOUT.INPUT_PADDING_EXTRA_LEFT;
       this.telInputEl.style.paddingLeft = `${inputPadding}px`;
@@ -2852,24 +2884,24 @@ var UI = class _UI {
   // Get the dropdown height (before it is added to the DOM)
   #getHiddenInlineDropdownHeight() {
     const body = _UI.#getBody();
-    this.#dropdownContentEl.classList.remove(CLASSES.HIDE);
+    this.#countrySelectorEl.classList.remove(CLASSES.HIDE);
     const tempContainer = createEl("div", {
-      class: "iti iti--inline-dropdown"
+      class: "iti iti--inline-country-selector"
     });
-    tempContainer.appendChild(this.#dropdownContentEl);
+    tempContainer.appendChild(this.#countrySelectorEl);
     tempContainer.style.visibility = "hidden";
     body.appendChild(tempContainer);
-    const height = this.#dropdownContentEl.offsetHeight;
+    const height = this.#countrySelectorEl.offsetHeight;
     body.removeChild(tempContainer);
     tempContainer.style.visibility = "";
-    this.#dropdownContentEl.classList.add(CLASSES.HIDE);
+    this.#countrySelectorEl.classList.add(CLASSES.HIDE);
     return height > 0 ? height : LAYOUT.FALLBACK_DROPDOWN_HEIGHT;
   }
   //* Update search results text (for a11y).
   #updateSearchResultsA11yText() {
-    const { i18n } = this.#options;
+    const { uiTranslations } = this.#options;
     const count = this.#countryListEl.childElementCount;
-    this.#searchResultsLiveRegionEl.textContent = i18n.searchSummaryAria(count);
+    this.#searchResultsLiveRegionEl.textContent = uiTranslations.searchSummaryAria(count);
   }
   //* Country search: Filter the countries according to the search query.
   #filterCountriesByQuery(query) {
@@ -2887,8 +2919,8 @@ var UI = class _UI {
     this.#showFilteredCountries(matchedCountries);
   }
   //* Pre-fill the search input with "+" and show all countries
-  //* (used when user types "+" in the phone input to open the dropdown).
-  //* Explicitly focus the search input (openDropdown skips this when
+  //* (used when user types "+" in the phone input to open the country selector).
+  //* Explicitly focus the search input (openCountrySelector skips this when
   //* dropdownAlwaysOpen, but here we need focus to redirect subsequent keystrokes).
   prefillSearchWithPlus() {
     this.#searchInputEl.value = "+";
@@ -2971,15 +3003,15 @@ var UI = class _UI {
       { signal }
     );
   }
-  //* Wire up triggers that open/close the dropdown: label click (focus input or swallow repeat click),
+  //* Wire up triggers that open/close the country selector: label click (focus input or swallow repeat click),
   //* selected-country click (open), and keydown on countryContainer (open on arrow/space/enter, close on tab).
-  bindAllInitialDropdownListeners(signal, onOpen, onClose) {
+  bindAllInitialCountrySelectorListeners(signal, onOpen, onClose) {
     const label = this.telInputEl.closest("label");
     if (label) {
       label.addEventListener(
         "click",
         (e) => {
-          if (!this.isDropdownOpen()) {
+          if (!this.isCountrySelectorOpen()) {
             this.telInputEl.focus();
           } else {
             e.preventDefault();
@@ -2991,7 +3023,7 @@ var UI = class _UI {
     this.#selectedCountryEl.addEventListener(
       "click",
       () => {
-        if (!this.isDropdownOpen() && !this.telInputEl.disabled && !this.telInputEl.readOnly) {
+        if (!this.isCountrySelectorOpen() && !this.telInputEl.disabled && !this.telInputEl.readOnly) {
           onOpen();
         }
       },
@@ -3006,7 +3038,7 @@ var UI = class _UI {
           KEYS.SPACE,
           KEYS.ENTER
         ];
-        if (!this.isDropdownOpen() && openKeys.includes(e.key)) {
+        if (!this.isCountrySelectorOpen() && openKeys.includes(e.key)) {
           e.preventDefault();
           e.stopPropagation();
           onOpen();
@@ -3018,24 +3050,24 @@ var UI = class _UI {
       { signal }
     );
   }
-  //* Open the dropdown: create a fresh AbortController, do the DOM work, and wire up all
-  //* dropdown-open listeners (which invoke the caller's onSelect / onClose callbacks).
-  openDropdown(onSelect, onClose) {
-    const { countrySearch, dropdownAlwaysOpen, dropdownContainer } = this.#options;
-    this.#dropdownAbortController = new AbortController();
+  //* Open the country selector: create a fresh AbortController, do the DOM work, and wire up all
+  //* open-state listeners (which invoke the caller's onSelect / onClose callbacks).
+  openCountrySelector(onSelect, onClose) {
+    const { countrySearch, dropdownAlwaysOpen } = this.#options;
+    this.#countrySelectorAbortController = new AbortController();
     this.ensureDropdownWidthSet();
-    if (dropdownContainer) {
-      this.#injectAndPositionDetachedDropdown();
+    if (this.#detachedCountrySelectorEl) {
+      this.#injectAndPositionDetachedCountrySelector();
     } else {
-      const positionBelow = this.#shouldPositionInlineDropdownBelowInput();
+      const positionBelow = this.#shouldPositionDropdownBelowInput();
       const distance = this.telInputEl.offsetHeight + LAYOUT.DROPDOWN_MARGIN;
       if (positionBelow) {
-        this.#dropdownContentEl.style.top = `${distance}px`;
+        this.#countrySelectorEl.style.top = `${distance}px`;
       } else {
-        this.#dropdownContentEl.style.bottom = `${distance}px`;
+        this.#countrySelectorEl.style.bottom = `${distance}px`;
       }
     }
-    this.#dropdownContentEl.classList.remove(CLASSES.HIDE);
+    this.#countrySelectorEl.classList.remove(CLASSES.HIDE);
     this.#selectedCountryEl.setAttribute(ARIA.EXPANDED, "true");
     const itemToHighlight = this.#selectedListItemEl ?? this.#countryListEl.firstElementChild;
     if (itemToHighlight) {
@@ -3044,7 +3076,7 @@ var UI = class _UI {
     if (countrySearch && !dropdownAlwaysOpen) {
       this.#searchInputEl.focus();
     }
-    if (this.#options.useFullscreenPopup && this.#detachedDropdownEl && window.visualViewport) {
+    if (this.#options.countrySelectorMode === COUNTRY_SELECTOR_MODE.FULLSCREEN && this.#detachedCountrySelectorEl && window.visualViewport) {
       window.visualViewport.addEventListener(
         "resize",
         () => {
@@ -3053,29 +3085,29 @@ var UI = class _UI {
             this.#scrollCountryListToItem(this.#highlightedListItemEl);
           }
         },
-        { signal: this.#dropdownAbortController.signal }
+        { signal: this.#countrySelectorAbortController.signal }
       );
     }
-    this.#dropdownArrowEl.classList.add(CLASSES.ARROW_UP);
-    this.#bindDropdownOpenListeners(onSelect, onClose);
+    this.#arrowEl.classList.add(CLASSES.ARROW_UP);
+    this.#bindCountrySelectorOpenListeners(onSelect, onClose);
   }
-  //* Wire up all listeners needed while the dropdown is open: list-item hover (highlight),
+  //* Wire up all listeners needed while the country selector is open: list-item hover (highlight),
   //* list-item click & enter key (select), click-off & escape (close), search input (filter),
-  //* (when countrySearch disabled) typed-char hidden search, and (when dropdown is in an external
-  //* container) close on window scroll.
-  #bindDropdownOpenListeners(onSelect, onClose) {
-    const signal = this.#dropdownAbortController.signal;
+  //* (when countrySearch disabled) typed-char hidden search, and (when the country selector is in an
+  //* external container) update (fixed) position on scroll/resize.
+  #bindCountrySelectorOpenListeners(onSelect, onClose) {
+    const signal = this.#countrySelectorAbortController.signal;
     this.#bindListItemHover(signal);
     this.#bindListItemClick(signal, onSelect);
     if (!this.#options.dropdownAlwaysOpen) {
       this.#bindOutsideClickToClose(signal, onClose);
     }
-    this.#bindDropdownKeydownListener(signal, onSelect, onClose);
+    this.#bindCountrySelectorKeydownListener(signal, onSelect, onClose);
     if (this.#options.countrySearch) {
       this.#bindSearchInputListener(signal);
     }
-    if (!this.#options.useFullscreenPopup && this.#options.dropdownContainer) {
-      window.addEventListener("scroll", onClose, { signal });
+    if (this.#options.countrySelectorMode === COUNTRY_SELECTOR_MODE.DROPDOWN && this.#options.dropdownParent && !supportsCssAnchor) {
+      document.addEventListener("scroll", onClose, { signal, capture: true, passive: true });
     }
   }
   //* When mouse over a list item, just highlight that one (so if they hit "enter" we know which to select).
@@ -3108,13 +3140,13 @@ var UI = class _UI {
       { signal }
     );
   }
-  //* Invoke onClickOff when the user clicks anywhere outside the dropdown.
+  //* Invoke onClickOff when the user clicks anywhere outside the country selector.
   #bindOutsideClickToClose(signal, onClickOff) {
     setTimeout(() => {
       document.documentElement.addEventListener(
         "click",
         (e) => {
-          if (!this.#dropdownContentEl.contains(e.target)) {
+          if (!this.#countrySelectorEl.contains(e.target)) {
             onClickOff();
           }
         },
@@ -3122,10 +3154,10 @@ var UI = class _UI {
       );
     }, 0);
   }
-  //* Keyboard navigation while the dropdown is open: arrow keys navigate, hidden-search keys filter,
-  //* and enter/escape invoke the caller's callbacks (which handle country selection / dropdown close).
+  //* Keyboard navigation while the country selector is open: arrow keys navigate, hidden-search keys filter,
+  //* and enter/escape invoke the caller's callbacks (which handle country selection / close).
   //* Uses keydown rather than keypress so non-char keys (arrow, esc) fire and so holding a key repeats.
-  #bindDropdownKeydownListener(signal, onEnter, onEscape) {
+  #bindCountrySelectorKeydownListener(signal, onEnter, onEscape) {
     let query = "";
     let queryTimer = null;
     const handleKeydown = (e) => {
@@ -3160,7 +3192,7 @@ var UI = class _UI {
       }
     };
     this.#selectedCountryEl?.addEventListener("keydown", handleKeydown, { signal });
-    this.#dropdownContentEl?.addEventListener("keydown", handleKeydown, { signal });
+    this.#countrySelectorEl?.addEventListener("keydown", handleKeydown, { signal });
   }
   //* Wire up country search input listener: typing filters the list, the clear button resets it.
   #bindSearchInputListener(signal) {
@@ -3197,7 +3229,7 @@ var UI = class _UI {
       this.#highlightListItem(next);
     }
   }
-  // Update the selected list item in the dropdown
+  // Update the selected list item in the country list
   #updateSelectedListItem(iso2) {
     if (this.#selectedListItemEl && this.#selectedListItemEl.dataset[DATA_KEYS.ISO2] !== iso2) {
       this.#selectedListItemEl.setAttribute(ARIA.SELECTED, "false");
@@ -3248,12 +3280,12 @@ var UI = class _UI {
     this.#countryListEl.scrollTop = 0;
     this.#updateSearchResultsA11yText();
   }
-  // UI: Close the dropdown (DOM + abort dropdown-scoped listeners).
-  closeDropdown() {
-    const { countrySearch, dropdownContainer } = this.#options;
-    this.#dropdownAbortController.abort();
-    this.#dropdownAbortController = null;
-    this.#dropdownContentEl.classList.add(CLASSES.HIDE);
+  // UI: Close the country selector (DOM + abort scoped listeners).
+  closeCountrySelector() {
+    const { countrySearch } = this.#options;
+    this.#countrySelectorAbortController.abort();
+    this.#countrySelectorAbortController = null;
+    this.#countrySelectorEl.classList.add(CLASSES.HIDE);
     this.#selectedCountryEl.setAttribute(ARIA.EXPANDED, "false");
     if (countrySearch) {
       this.#searchInputEl.removeAttribute(ARIA.ACTIVE_DESCENDANT);
@@ -3264,19 +3296,19 @@ var UI = class _UI {
         this.#highlightedListItemEl = null;
       }
     }
-    this.#dropdownArrowEl.classList.remove(CLASSES.ARROW_UP);
-    if (dropdownContainer) {
-      this.#detachedDropdownEl.remove();
-      this.#detachedDropdownEl.style.top = "";
-      this.#detachedDropdownEl.style.bottom = "";
-      this.#detachedDropdownEl.style.paddingLeft = "";
-      this.#detachedDropdownEl.style.paddingRight = "";
+    this.#arrowEl.classList.remove(CLASSES.ARROW_UP);
+    if (this.#detachedCountrySelectorEl) {
+      this.#detachedCountrySelectorEl.remove();
+      this.#detachedCountrySelectorEl.style.top = "";
+      this.#detachedCountrySelectorEl.style.bottom = "";
+      this.#detachedCountrySelectorEl.style.paddingLeft = "";
+      this.#detachedCountrySelectorEl.style.paddingRight = "";
     } else {
-      this.#dropdownContentEl.style.top = "";
-      this.#dropdownContentEl.style.bottom = "";
+      this.#countrySelectorEl.style.top = "";
+      this.#countrySelectorEl.style.bottom = "";
     }
   }
-  #shouldPositionInlineDropdownBelowInput() {
+  #shouldPositionDropdownBelowInput() {
     if (this.#options.dropdownAlwaysOpen) {
       return true;
     }
@@ -3285,41 +3317,54 @@ var UI = class _UI {
     const spaceBelow = window.innerHeight - inputPos.bottom;
     return spaceBelow >= this.#inlineDropdownHeight || spaceBelow >= spaceAbove;
   }
-  // inject dropdown into container and apply positioning styles
-  #injectAndPositionDetachedDropdown() {
-    const { dropdownContainer, useFullscreenPopup } = this.#options;
-    if (useFullscreenPopup) {
+  // inject the country selector into its detached wrapper and apply positioning styles
+  #injectAndPositionDetachedCountrySelector() {
+    const isFullscreen = this.#options.countrySelectorMode === COUNTRY_SELECTOR_MODE.FULLSCREEN;
+    const detachedParent = this.#getDetachedParent();
+    if (isFullscreen) {
       if (window.innerWidth >= LAYOUT.NARROW_VIEWPORT_WIDTH) {
         const inputPos = this.telInputEl.getBoundingClientRect();
-        this.#detachedDropdownEl.style.paddingLeft = `${inputPos.left}px`;
-        this.#detachedDropdownEl.style.paddingRight = `${window.innerWidth - inputPos.right}px`;
+        this.#detachedCountrySelectorEl.style.paddingLeft = `${inputPos.left}px`;
+        this.#detachedCountrySelectorEl.style.paddingRight = `${window.innerWidth - inputPos.right}px`;
       }
-    } else {
+    } else if (!supportsCssAnchor) {
       const inputPos = this.telInputEl.getBoundingClientRect();
-      this.#detachedDropdownEl.style.left = `${inputPos.left}px`;
-      const positionBelow = this.#shouldPositionInlineDropdownBelowInput();
-      if (positionBelow) {
-        this.#detachedDropdownEl.style.top = `${inputPos.bottom + LAYOUT.DROPDOWN_MARGIN}px`;
+      this.#detachedCountrySelectorEl.style.left = `${inputPos.left}px`;
+      if (this.#shouldPositionDropdownBelowInput()) {
+        this.#detachedCountrySelectorEl.style.top = `${inputPos.bottom + LAYOUT.DROPDOWN_MARGIN}px`;
       } else {
-        this.#detachedDropdownEl.style.top = "unset";
-        this.#detachedDropdownEl.style.bottom = `${window.innerHeight - inputPos.top + LAYOUT.DROPDOWN_MARGIN}px`;
+        this.#detachedCountrySelectorEl.style.top = "unset";
+        this.#detachedCountrySelectorEl.style.bottom = `${window.innerHeight - inputPos.top + LAYOUT.DROPDOWN_MARGIN}px`;
       }
     }
-    dropdownContainer.appendChild(this.#detachedDropdownEl);
+    detachedParent.appendChild(this.#detachedCountrySelectorEl);
+  }
+  //* Wire up CSS Anchor Positioning between the input and the detached country selector using a
+  //* unique anchor name per instance. Called once at build time — the matching styles in
+  //* intlTelInput.css only take effect in browsers that support anchor(); elsewhere these
+  //* properties are inert. We append our name to any existing anchor-name (read via
+  //* getComputedStyle so we pick up CSS-defined values), so consumer-set anchors on the input
+  //* are preserved. Caveat: this snapshots the consumer's value once — if they later change
+  //* anchor-name via CSS (e.g. a class swap), our inline write will shadow the change.
+  #setupCssAnchorPositioning() {
+    const anchorName = `--iti-anchor-${this.#id}`;
+    const existing = getComputedStyle(this.telInputEl).anchorName;
+    this.telInputEl.style.anchorName = existing && existing !== "none" ? `${existing}, ${anchorName}` : anchorName;
+    this.#detachedCountrySelectorEl.style.positionAnchor = anchorName;
   }
   // Adjust the fullscreen popup dimensions to match the visual viewport,
   // so it stays above the virtual keyboard on mobile devices.
   #adjustFullscreenPopupToViewport() {
     const vv = window.visualViewport;
-    if (!vv || !this.#detachedDropdownEl) {
+    if (!vv || !this.#detachedCountrySelectorEl) {
       return;
     }
     const virtualKeyboardHeight = window.innerHeight - vv.height;
-    this.#detachedDropdownEl.style.bottom = `${virtualKeyboardHeight}px`;
+    this.#detachedCountrySelectorEl.style.bottom = `${virtualKeyboardHeight}px`;
   }
-  // UI: Whether the dropdown is currently open (visible).
-  isDropdownOpen() {
-    return !this.#dropdownContentEl.classList.contains(CLASSES.HIDE);
+  // UI: Whether the country selector is currently open (visible).
+  isCountrySelectorOpen() {
+    return !this.#countrySelectorEl.classList.contains(CLASSES.HIDE);
   }
   // Toggle the loading spinner on the selected flag (used during auto-country geoIP lookup).
   setLoading(isLoading) {
@@ -3348,7 +3393,7 @@ var UI = class _UI {
   isLoading() {
     return this.#selectedFlagEl.classList.contains(CLASSES.LOADING);
   }
-  // Set the disabled state of the input and dropdown.
+  // Set the disabled state of the input and country selector.
   setDisabled(disabled) {
     this.telInputEl.disabled = disabled;
     if (this.#selectedCountryEl) {
@@ -3359,7 +3404,7 @@ var UI = class _UI {
       }
     }
   }
-  // Set the readonly state of the input and dropdown.
+  // Set the readonly state of the input and country selector.
   setReadonly(readonly) {
     this.telInputEl.readOnly = readonly;
     if (this.#selectedCountryEl) {
@@ -3370,12 +3415,12 @@ var UI = class _UI {
       }
     }
   }
-  setCountry(selectedCountryData) {
-    const { allowDropdown, showFlags, separateDialCode, i18n } = this.#options;
-    const name = selectedCountryData?.name;
-    const dialCode = selectedCountryData?.dialCode;
-    const iso2 = selectedCountryData?.iso2 ?? "";
-    if (allowDropdown) {
+  setSelectedCountry(selectedCountry) {
+    const { countrySelectorMode, showFlags, separateDialCode, uiTranslations } = this.#options;
+    const name = selectedCountry?.name;
+    const dialCode = selectedCountry?.dialCode;
+    const iso2 = selectedCountry?.iso2 ?? "";
+    if (countrySelectorMode !== COUNTRY_SELECTOR_MODE.OFF) {
       this.#updateSelectedListItem(iso2);
     }
     if (this.#selectedCountryEl) {
@@ -3384,13 +3429,13 @@ var UI = class _UI {
       let flagContent = null;
       if (iso2) {
         title = name;
-        ariaLabel = i18n.selectedCountryAriaLabel.replace("${countryName}", name).replace("${dialCode}", `+${dialCode}`);
+        ariaLabel = uiTranslations.selectedCountryAriaLabel.replace("${countryName}", name).replace("${dialCode}", `+${dialCode}`);
         if (!showFlags) {
           flagContent = buildGlobeIcon();
         }
       } else {
-        title = i18n.noCountrySelected;
-        ariaLabel = i18n.noCountrySelected;
+        title = uiTranslations.noCountrySelected;
+        ariaLabel = uiTranslations.noCountrySelected;
         flagContent = buildGlobeIcon();
       }
       this.#selectedFlagEl.className = flagClass;
@@ -3539,17 +3584,17 @@ var hasRegionlessDialCode = (number) => {
 };
 
 // packages/core/src/js/format/formatting.ts
-var stripSeparateDialCode = (fullNumber, hasValidDialCode, separateDialCode, selectedCountryData) => {
+var stripSeparateDialCode = (fullNumber, hasValidDialCode, separateDialCode, selectedCountry) => {
   if (!separateDialCode || !hasValidDialCode) {
     return fullNumber;
   }
-  const dialCode = `+${selectedCountryData.dialCode}`;
+  const dialCode = `+${selectedCountry.dialCode}`;
   const start = fullNumber[dialCode.length] === " " || fullNumber[dialCode.length] === "-" ? dialCode.length + 1 : dialCode.length;
   return fullNumber.substring(start);
 };
-var formatNumberAsYouType = (fullNumber, telInputValue, utils, selectedCountryData, separateDialCode) => {
-  const result = utils ? utils.formatNumberAsYouType(fullNumber, selectedCountryData?.iso2) : fullNumber;
-  const dialCode = selectedCountryData?.dialCode;
+var formatNumberAsYouType = (fullNumber, telInputValue, utils, selectedCountry, separateDialCode) => {
+  const result = utils ? utils.formatNumberAsYouType(fullNumber, selectedCountry?.iso2) : fullNumber;
+  const dialCode = selectedCountry?.dialCode;
   if (separateDialCode && telInputValue.charAt(0) !== "+" && result.includes(`+${dialCode}`)) {
     const afterDialCode = result.split(`+${dialCode}`)[1] || "";
     return afterDialCode.trim();
@@ -3680,8 +3725,8 @@ var Iti = class _Iti {
     this.#ui.telInputEl.value = this.#numerals.denormalise(asciiValue);
   }
   #createInitPromise(options) {
-    const { initialCountry, geoIpLookup, loadUtils } = options;
-    const needsAutoCountryDeferred = initialCountry === INITIAL_COUNTRY.AUTO && Boolean(geoIpLookup);
+    const { initialCountry, initialCountryLookup, loadUtils } = options;
+    const needsAutoCountryDeferred = !initialCountry && Boolean(initialCountryLookup);
     const needsUtilsDeferred = Boolean(loadUtils) && !intlTelInput.utils;
     if (needsAutoCountryDeferred) {
       this.#autoCountryDeferred = createDeferred();
@@ -3703,7 +3748,7 @@ var Iti = class _Iti {
     this.#initListeners();
     this.#startAsyncLoads();
     if (this.#options.dropdownAlwaysOpen) {
-      this.#openDropdown();
+      this.openCountrySelector();
     }
   }
   //********************
@@ -3726,8 +3771,8 @@ var Iti = class _Iti {
     const value = useAttribute ? attributeValue : inputValue;
     const dialCode = this.#getDialCode(value);
     const isRegionlessNanpNumber = isRegionlessNanp(value);
-    const { initialCountry, geoIpLookup } = this.#options;
-    const isAutoCountry = initialCountry === INITIAL_COUNTRY.AUTO && geoIpLookup;
+    const { initialCountry, initialCountryLookup } = this.#options;
+    const isAutoCountry = !initialCountry && Boolean(initialCountryLookup);
     const resolvedInitialCountry = isAutoCountry && intlTelInput.autoCountry ? intlTelInput.autoCountry : initialCountry;
     const doingAutoCountryLookup = isAutoCountry && !overrideAutoCountry && !intlTelInput.autoCountry;
     const isValidInitialCountry = isIso2(resolvedInitialCountry);
@@ -3756,11 +3801,11 @@ var Iti = class _Iti {
   //* Initialise the main event listeners: input keyup, and click selected country.
   #initListeners() {
     this.#bindAllTelInputListeners();
-    if (this.#options.allowDropdown) {
-      this.#ui.bindAllInitialDropdownListeners(
+    if (this.#options.countrySelectorMode !== COUNTRY_SELECTOR_MODE.OFF) {
+      this.#ui.bindAllInitialCountrySelectorListeners(
         this.#abortController.signal,
-        () => this.#openDropdown(),
-        () => this.#closeDropdown()
+        () => this.openCountrySelector(),
+        () => this.#closeCountrySelectorInternal()
       );
     }
     this.#ui.bindHiddenInputSubmitListener(
@@ -3769,7 +3814,7 @@ var Iti = class _Iti {
       () => this.#selectedCountry?.iso2 || ""
     );
   }
-  //* Init requests: utils script / geo ip lookup.
+  //* Init requests: utils script / initial country lookup.
   #startAsyncLoads() {
     if (this.#utilsDeferred) {
       const { loadUtils } = this.#options;
@@ -3793,7 +3838,7 @@ var Iti = class _Iti {
       }
     }
   }
-  //* Perform the geo ip lookup.
+  //* Perform the initial country lookup.
   async #loadAutoCountry() {
     if (intlTelInput.autoCountry) {
       this.#handleAutoCountryLoaded();
@@ -3804,14 +3849,14 @@ var Iti = class _Iti {
       return;
     }
     intlTelInput.startedLoadingAutoCountry = true;
-    if (typeof this.#options.geoIpLookup === "function") {
+    if (typeof this.#options.initialCountryLookup === "function") {
       let timeoutId;
       try {
         const iso2 = await Promise.race([
-          this.#options.geoIpLookup(),
+          this.#options.initialCountryLookup(),
           new Promise((_, reject) => {
             timeoutId = setTimeout(
-              () => reject(new Error("intl-tel-input: geoIpLookup timed out after 10s")),
+              () => reject(new Error("intl-tel-input: initialCountryLookup timed out after 10s")),
               1e4
             );
           })
@@ -3834,8 +3879,8 @@ var Iti = class _Iti {
       }
     }
   }
-  #openDropdownWithPlus() {
-    this.#openDropdown();
+  #openCountrySelectorWithPlus() {
+    this.openCountrySelector();
     this.#ui.prefillSearchWithPlus();
   }
   //* Delete the character just typed (the one immediately before the caret). Used by Android workarounds where we can't preventDefault on keydown.
@@ -3855,7 +3900,7 @@ var Iti = class _Iti {
   //* Android workaround for handling plus when separateDialCode enabled (as impossible to handle with keydown/keyup, for which e.key always returns "Unidentified", see https://stackoverflow.com/q/59584061/217866)
   #handleAndroidPlusKey(inputValue) {
     this.#removeJustTypedChar(inputValue);
-    this.#openDropdownWithPlus();
+    this.#openCountrySelectorWithPlus();
   }
   //* Android strictMode workaround: the keydown-based filter can't block these because e.key is "Unidentified" on Android virtual keyboards, so strip them here on input.
   #handleAndroidStrictReject(inputValue, rejectedInput) {
@@ -3925,7 +3970,7 @@ var Iti = class _Iti {
       strictMode,
       formatAsYouType,
       separateDialCode,
-      allowDropdown,
+      countrySelectorMode,
       countrySearch
     } = this.#options;
     const detail = e?.detail;
@@ -3935,7 +3980,7 @@ var Iti = class _Iti {
     let inputValue = this.#getTelInputValue();
     const isPaste = e?.inputType === INPUT_TYPES.PASTE;
     const isStrictPaste = strictMode && isPaste;
-    if (this.#isAndroid && !isPaste && e?.data === "+" && separateDialCode && allowDropdown && countrySearch) {
+    if (this.#isAndroid && !isPaste && e?.data === "+" && separateDialCode && countrySelectorMode !== COUNTRY_SELECTOR_MODE.OFF && countrySearch) {
       this.#handleAndroidPlusKey(inputValue);
       return;
     }
@@ -3982,13 +4027,13 @@ var Iti = class _Iti {
   //* On keydown event: (1) if strictMode then prevent invalid characters, (2) if separateDialCode then handle plus key
   //* Note that this fires BEFORE the input is updated.
   #handleKeydownEvent = (e) => {
-    const { strictMode, separateDialCode, allowDropdown, countrySearch } = this.#options;
+    const { strictMode, separateDialCode, countrySelectorMode, countrySearch } = this.#options;
     if (!e.key || e.key.length !== 1 || e.altKey || e.ctrlKey || e.metaKey) {
       return;
     }
-    if (separateDialCode && allowDropdown && countrySearch && e.key === "+") {
+    if (separateDialCode && countrySelectorMode !== COUNTRY_SELECTOR_MODE.OFF && countrySearch && e.key === "+") {
       e.preventDefault();
-      this.#openDropdownWithPlus();
+      this.#openCountrySelectorWithPlus();
       return;
     }
     if (!strictMode) {
@@ -4151,27 +4196,36 @@ var Iti = class _Iti {
     });
     this.#ui.telInputEl.dispatchEvent(e);
   }
-  //* Open the dropdown. Bail if already open — otherwise the existing AbortController gets overwritten
-  //* and its listeners leak. Reachable via openDropdownWithPlus when dropdownAlwaysOpen is set
-  #openDropdown() {
-    if (this.#ui.isDropdownOpen()) {
+  //* Open the country selector. Bail if already open — otherwise the existing AbortController gets overwritten
+  //* and its listeners leak. Reachable via openCountrySelectorWithPlus when dropdownAlwaysOpen is set.
+  //* Public so consumers can programmatically open the country selector.
+  openCountrySelector() {
+    if (this.#ui.isCountrySelectorOpen()) {
       return;
     }
-    this.#ui.openDropdown(
+    this.#ui.openCountrySelector(
       (li) => this.#selectListItem(li),
-      () => this.#closeDropdown()
+      () => this.#closeCountrySelectorInternal()
     );
-    this.#dispatchEvent(EVENTS.OPEN_COUNTRY_DROPDOWN);
+    this.#dispatchEvent(EVENTS.OPEN_COUNTRY_SELECTOR);
   }
   //* Update the input's value to the given number (format first if possible)
   //* NOTE: this is called from setInitialState, handleUtilsLoaded and setNumber.
   #updateValueFromNumber(fullNumber) {
-    const { formatOnDisplay, nationalMode, separateDialCode } = this.#options;
+    const { numberDisplayFormat, separateDialCode } = this.#options;
     let number = fullNumber;
-    if (formatOnDisplay && intlTelInput.utils && this.#selectedCountry) {
+    if (intlTelInput.utils && this.#selectedCountry) {
       const isRegionless = hasRegionlessDialCode(fullNumber);
-      const useNational = nationalMode && !isRegionless || !number.startsWith("+") && !separateDialCode;
-      const format = useNational ? NUMBER_FORMAT.NATIONAL : NUMBER_FORMAT.INTERNATIONAL;
+      const preserveUserNational = !number.startsWith("+") && !separateDialCode;
+      const useNational = numberDisplayFormat === NUMBER_FORMAT.NATIONAL && !isRegionless || preserveUserNational;
+      let format;
+      if (useNational) {
+        format = NUMBER_FORMAT.NATIONAL;
+      } else if (numberDisplayFormat === NUMBER_FORMAT.E164 && !isRegionless) {
+        format = NUMBER_FORMAT.E164;
+      } else {
+        format = NUMBER_FORMAT.INTERNATIONAL;
+      }
       number = intlTelInput.utils.formatNumber(
         number,
         this.#selectedCountry?.iso2,
@@ -4268,14 +4322,14 @@ var Iti = class _Iti {
     return null;
   }
   //* Update the selected country, dial code (if separateDialCode), placeholder, title, and selected list item.
-  //* Note: called from setInitialState, updateCountryFromNumber, selectListItem, setCountry.
+  //* Note: called from setInitialState, updateCountryFromNumber, selectListItem, setSelectedCountry.
   #updateSelectedCountry(iso2) {
     const prevIso2 = this.#selectedCountry?.iso2 || "";
     this.#selectedCountry = iso2 ? this.#countryByIso2.get(iso2) : null;
     if (this.#selectedCountry) {
       this.#fallbackCountryIso2 = this.#selectedCountry.iso2;
     }
-    this.#ui.setCountry(this.#selectedCountry);
+    this.#ui.setSelectedCountry(this.#selectedCountry);
     this.#updatePlaceholder();
     this.#updateMaxCoreNumberLength();
     return prevIso2 !== iso2;
@@ -4293,12 +4347,11 @@ var Iti = class _Iti {
     }
     let exampleNumber = intlTelInput.utils.getExampleNumber(
       iso2,
-      false,
       placeholderNumberType,
-      true
+      NUMBER_FORMAT.E164
     );
     let validNumber = exampleNumber;
-    while (intlTelInput.utils.isPossibleNumber(
+    while (intlTelInput.utils.isValidNumber(
       exampleNumber,
       iso2,
       allowedNumberTypes
@@ -4315,19 +4368,19 @@ var Iti = class _Iti {
   //* Update the input placeholder to an example number from the currently selected country.
   #updatePlaceholder() {
     const {
-      autoPlaceholder,
+      placeholderNumberPolicy,
       placeholderNumberType,
-      nationalMode,
+      numberDisplayFormat,
       customPlaceholder
     } = this.#options;
-    const shouldSetPlaceholder = autoPlaceholder === PLACEHOLDER_MODES.AGGRESSIVE || !this.#ui.hadInitialPlaceholder && autoPlaceholder === PLACEHOLDER_MODES.POLITE;
+    const shouldSetPlaceholder = placeholderNumberPolicy === PLACEHOLDER_POLICY.AGGRESSIVE || !this.#ui.hadInitialPlaceholder && placeholderNumberPolicy === PLACEHOLDER_POLICY.POLITE;
     if (!intlTelInput.utils || !shouldSetPlaceholder) {
       return;
     }
     let placeholder = this.#selectedCountry ? intlTelInput.utils.getExampleNumber(
       this.#selectedCountry.iso2,
-      nationalMode,
-      placeholderNumberType
+      placeholderNumberType,
+      numberDisplayFormat
     ) : "";
     placeholder = this.#prepareNumberForInput(placeholder);
     if (typeof customPlaceholder === "function") {
@@ -4335,36 +4388,40 @@ var Iti = class _Iti {
     }
     this.#ui.telInputEl.setAttribute("placeholder", placeholder);
   }
-  //* Called when the user selects a list item from the dropdown (no-op if listItem is null).
+  //* Called when the user selects a list item from the country list (no-op if listItem is null).
   #selectListItem(listItem) {
     if (!listItem) {
       return;
     }
     const iso2 = listItem.dataset[DATA_KEYS.ISO2];
     const countryChanged = this.#updateSelectedCountry(iso2);
-    this.#closeDropdown();
+    this.#closeCountrySelectorInternal();
     const dialCode = listItem.dataset[DATA_KEYS.DIAL_CODE];
     this.#updateDialCode(dialCode);
-    if (this.#options.formatOnDisplay) {
-      const inputValue = this.#getTelInputValue();
-      this.#updateValueFromNumber(inputValue);
-    }
+    const inputValue = this.#getTelInputValue();
+    this.#updateValueFromNumber(inputValue);
     this.#ui.telInputEl.focus();
     if (countryChanged) {
       this.#dispatchCountryChangeEvent();
       this.#dispatchEvent(EVENTS.INPUT, { isCountryChange: true });
     }
   }
-  //* Close the dropdown and unbind any listeners.
-  #closeDropdown(isDestroy) {
-    if (!this.#ui.isDropdownOpen() || this.#options.dropdownAlwaysOpen && !isDestroy) {
+  //* Public: close the country selector (consumer-callable; delegates to the internal helper
+  //* without the destroy-specific path).
+  closeCountrySelector() {
+    this.#closeCountrySelectorInternal();
+  }
+  //* Close the country selector and unbind any listeners. The isDestroy flag forces close even
+  //* when dropdownAlwaysOpen is set, so destroy() can fully tear down.
+  #closeCountrySelectorInternal(isDestroy) {
+    if (!this.#ui.isCountrySelectorOpen() || this.#options.dropdownAlwaysOpen && !isDestroy) {
       return;
     }
-    this.#ui.closeDropdown();
-    this.#dispatchEvent(EVENTS.CLOSE_COUNTRY_DROPDOWN);
+    this.#ui.closeCountrySelector();
+    this.#dispatchEvent(EVENTS.CLOSE_COUNTRY_SELECTOR);
   }
   //* Replace any existing dial code with the new one
-  //* Note: called from selectListItem and setCountry
+  //* Note: called from selectListItem and setSelectedCountry
   #updateDialCode(newDialCodeDigits) {
     const inputValue = this.#getTelInputValue();
     if (!inputValue.startsWith("+")) {
@@ -4444,7 +4501,7 @@ var Iti = class _Iti {
   //**************************
   //*  INTERNAL METHODS
   //**************************
-  //* Called when the geoip call returns.
+  //* Called when the initial country lookup returns.
   #handleAutoCountryLoaded() {
     if (!this.#autoCountryDeferred || !intlTelInput.autoCountry) {
       return;
@@ -4453,15 +4510,17 @@ var Iti = class _Iti {
       this.#autoCountryDeferred.resolve();
       return;
     }
-    if (this.#ui.isLoading()) {
-      this.setCountry(intlTelInput.autoCountry);
+    const isFocused = document.activeElement === this.#ui.telInputEl;
+    const hasTypedValue = Boolean(this.#getTelInputValue());
+    if (this.#ui.isLoading() && !(isFocused && hasTypedValue)) {
+      this.setSelectedCountry(intlTelInput.autoCountry);
     } else {
       this.#fallbackCountryIso2 = intlTelInput.autoCountry;
     }
     this.#ui.setLoading(false);
     this.#autoCountryDeferred.resolve();
   }
-  //* Called when the geoip call fails or times out.
+  //* Called when the initial country lookup fails or times out.
   #handleAutoCountryFailure() {
     if (!this.#isActive) {
       this.#autoCountryDeferred?.reject();
@@ -4482,7 +4541,8 @@ var Iti = class _Iti {
       return;
     }
     const inputValue = this.#getTelInputValue();
-    if (inputValue) {
+    const isFocused = document.activeElement === this.#ui.telInputEl;
+    if (inputValue && !isFocused) {
       this.#updateValueFromNumber(inputValue);
     }
     if (this.#selectedCountry) {
@@ -4508,8 +4568,8 @@ var Iti = class _Iti {
       return;
     }
     this.#isActive = false;
-    if (this.#options.allowDropdown) {
-      this.#closeDropdown(true);
+    if (this.#options.countrySelectorMode !== COUNTRY_SELECTOR_MODE.OFF) {
+      this.#closeCountrySelectorInternal(true);
     }
     this.#abortController.abort();
     this.#ui.destroy();
@@ -4557,7 +4617,7 @@ var Iti = class _Iti {
     );
   }
   //* Get the country data for the currently selected country.
-  getSelectedCountryData() {
+  getSelectedCountry() {
     return this.#selectedCountry ?? null;
   }
   //* Get the validation error e.g. "TOO_SHORT" / "TOO_LONG", or null if it can't be determined / instance is destroyed.
@@ -4612,7 +4672,7 @@ var Iti = class _Iti {
     if (!this.#selectedCountry && !hasRegionlessDialCode(value)) {
       return false;
     }
-    const check = mode === "precise" ? intlTelInput.utils.isValidNumber : intlTelInput.utils.isPossibleNumber;
+    const check = mode === "precise" ? intlTelInput.utils.isValidNumberPrecise : intlTelInput.utils.isValidNumber;
     if (!check(value, iso2, allowedNumberTypes)) {
       return false;
     }
@@ -4625,7 +4685,7 @@ var Iti = class _Iti {
     return true;
   }
   //* Update the selected country, and update the input value accordingly.
-  setCountry(iso2) {
+  setSelectedCountry(iso2) {
     if (!this.#isActive) {
       return;
     }
@@ -4640,10 +4700,8 @@ var Iti = class _Iti {
     }
     this.#updateSelectedCountry(iso2Lower);
     this.#updateDialCode(this.#selectedCountry?.dialCode || "");
-    if (this.#options.formatOnDisplay) {
-      const inputValue = this.#getTelInputValue();
-      this.#updateValueFromNumber(inputValue);
-    }
+    const inputValue = this.#getTelInputValue();
+    this.#updateValueFromNumber(inputValue);
     this.#dispatchCountryChangeEvent();
     this.#dispatchEvent(EVENTS.INPUT, { isCountryChange: true });
   }
@@ -4668,14 +4726,14 @@ var Iti = class _Iti {
     this.#options.placeholderNumberType = type;
     this.#updatePlaceholder();
   }
-  // Set the disabled state of the input and dropdown.
+  // Set the disabled state of the input and country selector.
   setDisabled(disabled) {
     if (!this.#isActive) {
       return;
     }
     this.#ui.setDisabled(disabled);
   }
-  // Set the readonly state of the input and dropdown.
+  // Set the readonly state of the input and country selector.
   setReadonly(readonly) {
     if (!this.#isActive) {
       return;
@@ -4685,7 +4743,7 @@ var Iti = class _Iti {
   //********************
   //*  STATIC METHODS
   //********************
-  // Internal instance notification used by utils/geoip loaders.
+  // Internal instance notification used by utils/initial-country loaders.
   // Kept public so module-level helpers (e.g. attachUtils) can call it, while still allowing
   // access to private instance methods.
   static forEachInstance(method, ...args) {
@@ -4749,8 +4807,8 @@ var intlTelInput = Object.assign(
     defaults,
     //* Using a static var like this allows us to mock it in the tests.
     documentReady: () => document.readyState === "complete",
-    //* Get the country data object.
-    getCountryData: () => data_default,
+    //* Get the full list of all countries the library knows about.
+    getAllCountries: () => data_default,
     //* A getter for the core library instance.
     getInstance: (input) => {
       const id = input.dataset[DATA_KEYS.INSTANCE_ID];
@@ -4761,17 +4819,21 @@ var intlTelInput = Object.assign(
     attachUtils,
     startedLoadingUtils: false,
     startedLoadingAutoCountry: false,
-    version: "28.1.0",
+    version: "29.0.1",
     NUMBER_FORMAT,
     NUMBER_TYPE,
-    VALIDATION_ERROR
+    VALIDATION_ERROR,
+    PLACEHOLDER_POLICY,
+    COUNTRY_SELECTOR_MODE
   }
 );
 var intlTelInput_default = intlTelInput;
 export {
+  COUNTRY_SELECTOR_MODE,
   Iti,
   NUMBER_FORMAT,
   NUMBER_TYPE,
+  PLACEHOLDER_POLICY,
   VALIDATION_ERROR,
   intlTelInput_default as default
 };