intl-tel-input 28.1.0 → 29.0.1

package/dist/js/intlTelInput.js

@@ -1,5 +1,5 @@
 /*
- * International Telephone Input v28.1.0
+ * International Telephone Input v29.0.1
  * git+https://github.com/jackocnr/intl-tel-input.git
  * Licensed under the MIT license
  */
@@ -26,9 +26,11 @@ var _factory = (() => {
   // packages/core/src/js/intlTelInput.ts
   var intlTelInput_exports = {};
   __export(intlTelInput_exports, {
+    COUNTRY_SELECTOR_MODE: () => COUNTRY_SELECTOR_MODE,
     Iti: () => Iti,
     NUMBER_FORMAT: () => NUMBER_FORMAT,
     NUMBER_TYPE: () => NUMBER_TYPE,
+    PLACEHOLDER_POLICY: () => PLACEHOLDER_POLICY,
     VALIDATION_ERROR: () => VALIDATION_ERROR,
     default: () => intlTelInput_default
   });
@@ -1787,8 +1789,8 @@ var _factory = (() => {
 
   // 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
@@ -1835,9 +1837,9 @@ var _factory = (() => {
   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
@@ -1865,14 +1867,17 @@ var _factory = (() => {
     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",
@@ -1905,8 +1910,9 @@ var _factory = (() => {
   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
@@ -1924,7 +1930,7 @@ var _factory = (() => {
     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",
@@ -1947,63 +1953,63 @@ var _factory = (() => {
   // 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.
@@ -2012,12 +2018,10 @@ var _factory = (() => {
     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);
@@ -2029,7 +2033,7 @@ var _factory = (() => {
     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}`);
   };
@@ -2075,30 +2079,48 @@ var _factory = (() => {
         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;
@@ -2124,8 +2146,8 @@ var _factory = (() => {
           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);
@@ -2133,9 +2155,9 @@ var _factory = (() => {
           }
           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;
@@ -2152,9 +2174,9 @@ var _factory = (() => {
           }
           break;
         }
-        case "i18n":
+        case "uiTranslations":
           if (value && !isPlainObject(value)) {
-            warnOption("i18n", "an object", value);
+            warnOption("uiTranslations", "an object", value);
             break;
           }
           validatedOptions[key] = value;
@@ -2172,12 +2194,8 @@ var _factory = (() => {
             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;
@@ -2240,30 +2258,29 @@ var _factory = (() => {
     }
   };
   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
@@ -2474,6 +2491,7 @@ var _factory = (() => {
   };
 
   // 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;
@@ -2488,8 +2506,8 @@ var _factory = (() => {
     #selectedCountryEl;
     #selectedFlagEl;
     #selectedDialCodeEl;
-    #dropdownArrowEl;
-    #dropdownContentEl;
+    #arrowEl;
+    #countrySelectorEl;
     #searchIconEl;
     #searchInputEl;
     #searchClearButtonEl;
@@ -2498,11 +2516,11 @@ var _factory = (() => {
     #hiddenInputCountryEl;
     #noResultsMessageEl;
     #searchResultsLiveRegionEl;
-    #detachedDropdownEl;
+    #detachedCountrySelectorEl;
     #selectedListItemEl = null;
     #highlightedListItemEl = null;
     #listItemByIso2 = /* @__PURE__ */ new Map();
-    #dropdownAbortController = null;
+    #countrySelectorAbortController = null;
     #resizeObserver;
     // public
     telInputEl;
@@ -2527,7 +2545,7 @@ var _factory = (() => {
         );
       }
     }
-    //* 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;
@@ -2550,13 +2568,13 @@ var _factory = (() => {
       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 });
@@ -2567,8 +2585,9 @@ var _factory = (() => {
       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(
@@ -2577,16 +2596,16 @@ var _factory = (() => {
         { 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
         );
@@ -2610,8 +2629,8 @@ var _factory = (() => {
         { class: CLASSES.FLAG },
         selectedCountryPrimary
       );
-      if (allowDropdown) {
-        this.#dropdownArrowEl = createEl(
+      if (enableCountrySelector) {
+        this.#arrowEl = createEl(
           "div",
           { class: "iti__arrow", [ARIA.HIDDEN]: "true" },
           selectedCountryPrimary
@@ -2624,38 +2643,39 @@ var _factory = (() => {
           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();
@@ -2666,40 +2686,54 @@ var _factory = (() => {
           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",
@@ -2717,11 +2751,11 @@ var _factory = (() => {
           // 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"
@@ -2733,7 +2767,7 @@ var _factory = (() => {
         {
           type: "button",
           class: `iti__search-clear ${CLASSES.HIDE}`,
-          [ARIA.LABEL]: i18n.clearSearchAriaLabel,
+          [ARIA.LABEL]: uiTranslations.clearSearchAriaLabel,
           tabindex: "-1"
         },
         searchWrapper
@@ -2742,7 +2776,7 @@ var _factory = (() => {
       this.#searchResultsLiveRegionEl = createEl(
         "span",
         { class: "iti__a11y-text" },
-        this.#dropdownContentEl
+        this.#countrySelectorEl
       );
       this.#noResultsMessageEl = createEl(
         "div",
@@ -2751,9 +2785,9 @@ var _factory = (() => {
           [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) {
@@ -2763,12 +2797,12 @@ var _factory = (() => {
       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}"]`
@@ -2833,7 +2867,7 @@ var _factory = (() => {
     //* 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`;
@@ -2887,24 +2921,24 @@ var _factory = (() => {
     // 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) {
@@ -2922,8 +2956,8 @@ var _factory = (() => {
       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 = "+";
@@ -3006,15 +3040,15 @@ var _factory = (() => {
         { 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();
@@ -3026,7 +3060,7 @@ var _factory = (() => {
       this.#selectedCountryEl.addEventListener(
         "click",
         () => {
-          if (!this.isDropdownOpen() && !this.telInputEl.disabled && !this.telInputEl.readOnly) {
+          if (!this.isCountrySelectorOpen() && !this.telInputEl.disabled && !this.telInputEl.readOnly) {
             onOpen();
           }
         },
@@ -3041,7 +3075,7 @@ var _factory = (() => {
             KEYS.SPACE,
             KEYS.ENTER
           ];
-          if (!this.isDropdownOpen() && openKeys.includes(e.key)) {
+          if (!this.isCountrySelectorOpen() && openKeys.includes(e.key)) {
             e.preventDefault();
             e.stopPropagation();
             onOpen();
@@ -3053,24 +3087,24 @@ var _factory = (() => {
         { 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) {
@@ -3079,7 +3113,7 @@ var _factory = (() => {
       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",
           () => {
@@ -3088,29 +3122,29 @@ var _factory = (() => {
               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).
@@ -3143,13 +3177,13 @@ var _factory = (() => {
         { 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();
             }
           },
@@ -3157,10 +3191,10 @@ var _factory = (() => {
         );
       }, 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) => {
@@ -3195,7 +3229,7 @@ var _factory = (() => {
         }
       };
       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) {
@@ -3232,7 +3266,7 @@ var _factory = (() => {
         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");
@@ -3283,12 +3317,12 @@ var _factory = (() => {
       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);
@@ -3299,19 +3333,19 @@ var _factory = (() => {
           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;
       }
@@ -3320,41 +3354,54 @@ var _factory = (() => {
       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) {
@@ -3383,7 +3430,7 @@ var _factory = (() => {
     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) {
@@ -3394,7 +3441,7 @@ var _factory = (() => {
         }
       }
     }
-    // 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) {
@@ -3405,12 +3452,12 @@ var _factory = (() => {
         }
       }
     }
-    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) {
@@ -3419,13 +3466,13 @@ var _factory = (() => {
         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;
@@ -3574,17 +3621,17 @@ var _factory = (() => {
   };
 
   // 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();
@@ -3715,8 +3762,8 @@ var _factory = (() => {
       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();
@@ -3738,7 +3785,7 @@ var _factory = (() => {
       this.#initListeners();
       this.#startAsyncLoads();
       if (this.#options.dropdownAlwaysOpen) {
-        this.#openDropdown();
+        this.openCountrySelector();
       }
     }
     //********************
@@ -3761,8 +3808,8 @@ var _factory = (() => {
       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);
@@ -3791,11 +3838,11 @@ var _factory = (() => {
     //* 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(
@@ -3804,7 +3851,7 @@ var _factory = (() => {
         () => 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;
@@ -3828,7 +3875,7 @@ var _factory = (() => {
         }
       }
     }
-    //* Perform the geo ip lookup.
+    //* Perform the initial country lookup.
     async #loadAutoCountry() {
       if (intlTelInput.autoCountry) {
         this.#handleAutoCountryLoaded();
@@ -3839,14 +3886,14 @@ var _factory = (() => {
         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
               );
             })
@@ -3869,8 +3916,8 @@ var _factory = (() => {
         }
       }
     }
-    #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.
@@ -3890,7 +3937,7 @@ var _factory = (() => {
     //* 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) {
@@ -3960,7 +4007,7 @@ var _factory = (() => {
         strictMode,
         formatAsYouType,
         separateDialCode,
-        allowDropdown,
+        countrySelectorMode,
         countrySearch
       } = this.#options;
       const detail = e?.detail;
@@ -3970,7 +4017,7 @@ var _factory = (() => {
       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;
       }
@@ -4017,13 +4064,13 @@ var _factory = (() => {
     //* 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) {
@@ -4186,27 +4233,36 @@ var _factory = (() => {
       });
       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,
@@ -4303,14 +4359,14 @@ var _factory = (() => {
       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;
@@ -4328,12 +4384,11 @@ var _factory = (() => {
       }
       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
@@ -4350,19 +4405,19 @@ var _factory = (() => {
     //* 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") {
@@ -4370,36 +4425,40 @@ var _factory = (() => {
       }
       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("+")) {
@@ -4479,7 +4538,7 @@ var _factory = (() => {
     //**************************
     //*  INTERNAL METHODS
     //**************************
-    //* Called when the geoip call returns.
+    //* Called when the initial country lookup returns.
     #handleAutoCountryLoaded() {
       if (!this.#autoCountryDeferred || !intlTelInput.autoCountry) {
         return;
@@ -4488,15 +4547,17 @@ var _factory = (() => {
         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();
@@ -4517,7 +4578,8 @@ var _factory = (() => {
         return;
       }
       const inputValue = this.#getTelInputValue();
-      if (inputValue) {
+      const isFocused = document.activeElement === this.#ui.telInputEl;
+      if (inputValue && !isFocused) {
         this.#updateValueFromNumber(inputValue);
       }
       if (this.#selectedCountry) {
@@ -4543,8 +4605,8 @@ var _factory = (() => {
         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();
@@ -4592,7 +4654,7 @@ var _factory = (() => {
       );
     }
     //* 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.
@@ -4647,7 +4709,7 @@ var _factory = (() => {
       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;
       }
@@ -4660,7 +4722,7 @@ var _factory = (() => {
       return true;
     }
     //* Update the selected country, and update the input value accordingly.
-    setCountry(iso2) {
+    setSelectedCountry(iso2) {
       if (!this.#isActive) {
         return;
       }
@@ -4675,10 +4737,8 @@ var _factory = (() => {
       }
       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 });
     }
@@ -4703,14 +4763,14 @@ var _factory = (() => {
       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;
@@ -4720,7 +4780,7 @@ var _factory = (() => {
     //********************
     //*  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) {
@@ -4784,8 +4844,8 @@ var _factory = (() => {
       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];
@@ -4796,10 +4856,12 @@ var _factory = (() => {
       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;