intl-tel-input 25.15.0 → 26.0.0-beta.1

package/README.md

@@ -100,13 +100,11 @@ _Note: We have now dropped support for all versions of Internet Explorer because
 
 2. Import the CSS: `import 'intl-tel-input/build/css/intlTelInput.css';`
 
-3. Set the path to flags.webp and globe.webp in your CSS, by overriding the CSS variables
+3. Set the path to flags.webp in your CSS, by overriding the CSS variables
   ```css
   .iti {
     --iti-path-flags-1x: url('path/to/flags.webp');
     --iti-path-flags-2x: url('path/to/flags@2x.webp');
-    --iti-path-globe-1x: url('path/to/globe.webp');
-    --iti-path-globe-2x: url('path/to/globe@2x.webp');
   }
   ```
 
@@ -130,13 +128,11 @@ Most bundlers (such as Webpack, Vite, or Parcel) will see this and place the [ut
   <link rel="stylesheet" href="path/to/intlTelInput.css">
   ```
 
-3. Set the path to flags.webp and globe.webp in your CSS, by overriding the CSS variables
+3. Set the path to flags.webp in your CSS, by overriding the CSS variables
   ```css
   .iti {
     --iti-path-flags-1x: url('path/to/flags.webp');
     --iti-path-flags-2x: url('path/to/flags@2x.webp');
-    --iti-path-globe-1x: url('path/to/globe.webp');
-    --iti-path-globe-2x: url('path/to/globe@2x.webp');
   }
   ```
 
@@ -169,6 +165,10 @@ When you initialise the plugin, the first argument is the input element, and the
 Type: `Boolean` Default: `true`  
 Whether or not to allow the dropdown. If disabled, there is no dropdown arrow, and the selected country is not clickable. Also, if showFlags is enabled, we display the selected flag on the right instead, because it is just a marker of state. Note that if `separateDialCode` is enabled, `allowDropdown` is forced to `true` as the dropdown is required when the user types "+" in this case. Play with this option on [Storybook](https://intl-tel-input.com/storybook/?path=/docs/intltelinput--allowdropdown) (using the React component).
 
+**allowNumberExtensions**  
+Type: `Boolean` Default: `false`  
+Whether or not the validation methods return `true` for numbers containing extensions, e.g. "+1 702 123-1234 ext. 1234".
+
 **allowPhonewords**  
 Type: `Boolean` Default: `false`  
 Whether or not the validation methods return `true` for numbers containing phonewords, e.g. "+1 702 FLOWERS".
@@ -181,6 +181,10 @@ Set the input's placeholder to an example number for the selected country, and u
 Type: `String` Default: `""`  
 Additional classes to add to the (injected) wrapper `<div>`.
 
+**countryNameLocale**  
+Type: `String` Default: `"en"`  
+The locale to pass to `Intl.DisplayNames` to generate the country names.
+
 **countryOrder**  
 Type: `Array` Default: `null`  
 Specify the ordering for the country list with an array of iso2 country codes. Any omitted countries will appear after those specified, in alphabetical order, e.g. setting `countryOrder` to `["jp", "kr"]` will result in the list: Japan, South Korea, Afghanistan, Albania, Algeria etc...
@@ -261,9 +265,9 @@ This will generate the following (hidden) elements, which will be automatically
 
 **i18n**  
 Type: `Object` Default: `{}`  
-Allows you to specify translation strings for the 200+ country names, as well as other user interface text (e.g. the placeholder text for the country search input). The easiest way to do this is to import one of the [provided translation modules](https://github.com/jackocnr/intl-tel-input/tree/master/src/js/intl-tel-input/i18n) and set `i18n` to that value (see option 1 below). You can also override one or more individual keys this way (see option 1 below). Alternatively, you can provide your own custom translations (see option 2 below). If providing your own, you will need to specify all the country names (which can be copied from the country-list project, e.g. here are the [country names in French](https://github.com/umpirsky/country-list/blob/master/data/fr/country.json)), as well as a few UI strings (listed below). [See example](https://intl-tel-input.com/examples/localise-countries.html).
+Allows you to specify translation strings for the user interface text (e.g. the placeholder text for the country search input) or to override any country names (generated with `Intl.DisplayNames`). The easiest way to do this is to import one of the [provided translation modules](https://github.com/jackocnr/intl-tel-input/tree/master/src/js/intl-tel-input/i18n) and set the `i18n` initialisation option to that value (see option 1 below). You can also override one or more individual keys this way (see option 1 below). Alternatively, you can provide your own custom translations (see option 2 below). If providing your own, see the required UI strings listed below. [See example](https://intl-tel-input.com/examples/localise-countries.html).
 
-If we don't currently support a language you need, it's easy to [contribute this](https://github.com/jackocnr/intl-tel-input/blob/master/.github/CONTRIBUTING.md#adding-a-new-translation) yourself - you only need to provide a handful of UI translation strings, as we automatically pull in the country names from the country-list project.
+If we don't currently support a language you need, it's easy to [contribute this](https://github.com/jackocnr/intl-tel-input/blob/master/.github/CONTRIBUTING.md#adding-a-new-translation) yourself - you only need to provide a handful of UI translation strings.
 
 Option 1: import one of the provided translation modules
 ```js
@@ -286,13 +290,6 @@ Option 2: define your own custom translations
 ```js
 intlTelInput(input, {
   i18n: {
-    // Country names - see the full list in src/js/intl-tel-input/i18n/en/countries.ts
-    af: "Afghanistan",
-    al: "Albania",
-    dz: "Algeria",
-    as: "American Samoa",
-    ad: "Andorra",
-    ...
     // Aria label for the selected country element, when there is a country selected
     selectedCountryAriaLabel: "Change country, selected ${countryName} (${dialCode})",
     // Aria label and title text for the selected country element, when no country is selected
@@ -303,18 +300,13 @@ intlTelInput(input, {
     searchPlaceholder: "Search",
     // Aria label for the clear search button
     clearSearchAriaLabel: "Clear search",
-    // Visible text and screen reader message for when the search produces no results
-    zeroSearchResults: "No results found",
-    // Screen reader message for when the search produces 1 result
-    oneSearchResult: "1 result found",
-    // Screen reader message for when the search produces multiple results
-    multipleSearchResults: "${count} results found",
-    // OPTIONAL: For more complex pluralisation cases, e.g. Polish or Arabic, you can implement your own logic, like below. In this case, you can omit the "one" and "multiple" keys above.
-    searchResultsText(count) {
-      // NOTE: zero results are always handled by "zeroSearchResults" above
+    // Visible text for when the search produces no results
+    searchEmptyState: "No results found",
+    // Screen reader summary of search results
+    searchSummaryAria(count) {
+      if (count === 0) return "No results found";
       if (count === 1) return "1 result found";
-      if (count < 5) return `Some ${count} results found`;
-      return `Many ${count} results found`;
+      return `${count} results found`;
     }
   }
 });
@@ -376,15 +368,15 @@ __Note: if the user enters their number with autofill or by copying and pasting
 
 **strictMode**  
 Type: `Boolean` Default: `false`  
-As the user types in the input, ignore any irrelevant characters. The user can only enter numeric characters and an optional plus at the beginning. Cap the length at the maximum valid number length (this respects `validationNumberTypes`). Requires the [utils script to be loaded](#loading-the-utilities-script). [See example](https://intl-tel-input.com/examples/strict-mode.html).
+As the user types in the input, ignore any irrelevant characters. The user can only enter numeric characters and an optional plus at the beginning. Cap the length at the maximum valid number length (this respects `allowedNumberTypes`). Requires the [utils script to be loaded](#loading-the-utilities-script). [See example](https://intl-tel-input.com/examples/strict-mode.html).
 
 **useFullscreenPopup**  
 Type: `Boolean` Default: `true on mobile devices, false otherwise`  
 Control when the country list appears as a fullscreen popup vs an inline dropdown. By default, it will appear as a fullscreen popup on mobile devices (based on user-agent and screen width), to make better use of the limited space (similar to how a native `<select>` works), and as an inline dropdown on larger devices/screens. Play with this option on [Storybook](https://intl-tel-input.com/storybook/?path=/docs/intltelinput--usefullscreenpopup) (using the React component).
 
-**validationNumberTypes**  
-Type: `String[]` Default: `["MOBILE"]`  
-Specify an array of [the keys](https://github.com/jackocnr/intl-tel-input/blob/master/src/js/utils.js#L198) from the enum `intlTelInput.utils.numberType` to set the number type(s) to enforce during validation, as well as the number length to enforce with `strictMode`. Set it to `null` to not enforce any particular type. By default, it's set to `["MOBILE"]` so `isValidNumber` will only return `true` for mobile numbers. Alternatively, you could set it to, for example, `["TOLL_FREE", "PREMIUM_RATE"]` to get `isValidNumber` to return `true` for only those kinds of numbers.
+**allowedNumberTypes**  
+Type: `String[]` Default: `["MOBILE", "FIXED_LINE"]`  
+Specify an array of [the keys](https://github.com/jackocnr/intl-tel-input/blob/master/src/js/utils.js#L198) from the enum `intlTelInput.utils.numberType` to set the number type(s) to enforce during validation, as well as the number length to enforce with `strictMode`. Set it to `null` to not enforce any particular type. By default, it's set to `["MOBILE", "FIXED_LINE"]` so `isValidNumber` (etc) will only return `true` for those kinds of numbers. Alternatively, you could set it to simply `["MOBILE"]` if you only wanted to accept mobile numbers as valid. _Note: previously named `validationNumberTypes`._
 
 ## Instance Methods
 In these examples, `iti` refers to the plugin instance which gets returned when you initialise the plugin, e.g.
@@ -454,7 +446,7 @@ if (error === intlTelInput.utils.validationError.TOO_SHORT) {
 ```
 
 **isValidNumber**  
-(Note: only returns `true` for valid <ins>mobile numbers</ins> by default - see `validationNumberTypes`)  
+(Note: only returns `true` for valid <ins>mobile numbers</ins> by default - see `allowedNumberTypes`)  
 Check if the current number is valid based on its length - [see example](https://intl-tel-input.com/examples/validation-practical.html), which should be sufficient for most use cases. See `isValidNumberPrecise` (DANGEROUS) for more precise validation, but the advantage of `isValidNumber` is that it is much more future-proof, as while countries around the world regularly update their number rules, they rarely change their number lengths. If this method returns `false`, you can use `getValidationError` to get more information. Requires the [utils script to be loaded](#loading-the-utilities-script).  
 ```js
 const isValid = iti.isValidNumber();
@@ -462,7 +454,7 @@ const isValid = iti.isValidNumber();
 Returns: `true`/`false`
 
 **isValidNumberPrecise** ⚠️ DANGEROUS  
-(Note: only returns `true` for valid <ins>mobile numbers</ins> by default - see `validationNumberTypes`)  
+(Note: only returns `true` for valid <ins>mobile numbers</ins> by default - see `allowedNumberTypes`)  
 Check if the current number is valid using precise matching rules for each country/area code, etc - [see example](https://intl-tel-input.com/examples/validation.html). Note that these rules change each month for various countries around the world, so you need to constantly keep the plugin up-to-date (e.g. via an automated script) else <ins>you will start rejecting valid numbers</ins>. For a simpler and more future-proof form of validation, see `isValidNumber` above. If validation fails, you can use `getValidationError` to get more information. Requires the [utils script to be loaded](#loading-the-utilities-script).  
 ```js
 const isValid = iti.isValidNumberPrecise();
@@ -545,8 +537,6 @@ This is triggered when the user closes the dropdown.
 ## Theming / Dark Mode
 There are lots of CSS variables available for theming. See [intlTelInput.scss](https://github.com/jackocnr/intl-tel-input/blob/master/src/css/intlTelInput.scss) for the full list.
 
-As for the empty state (globe icon), the default version is dark grey, and we also provide a "light" version that should work better with a dark theme. Alternatively, it's easy to [re-generate the globe icon](https://free-icon-rainbow.com/international-call-free-icon) in whatever colour you need for your theme. We recommend you download it in the highest resolution possible, and then scale the image down to the required sizes (20px wide for the default version and 40px wide for the @2x version).
-
 Dark mode example (with screenshot below):
 ```css
 @media (prefers-color-scheme: dark) {
@@ -554,10 +544,8 @@ Dark mode example (with screenshot below):
     --iti-border-color: #5b5b5b;
     --iti-dialcode-color: #999999;
     --iti-dropdown-bg: #0d1117;
-    --iti-arrow-color: #aaaaaa;
+    --iti-icon-color: #aaaaaa;
     --iti-hover-color: #30363d;
-    --iti-path-globe-1x: url("path/to/globe_light.webp");
-    --iti-path-globe-2x: url("path/to/globe_light@2x.webp");
   }
 }
 ```
@@ -587,7 +575,7 @@ We provide [translations](https://github.com/jackocnr/intl-tel-input/tree/master
 
 Supported languages: Arabic, Albanian, Bengali, Bosnian, Bulgarian, Catalan, Chinese, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Lithuanian, Marathi, Norwegian, Persian, Polish, Portuguese, Romanian, Russian, Serbian, Slovak, Slovenian, Spanish, Swedish, Telugu, Thai, Turkish, Ukrainian, Urdu, Uzbek, Vietnamese.
 
-If we don't currently support a language you need, it's easy to [contribute this](https://github.com/jackocnr/intl-tel-input/blob/master/.github/CONTRIBUTING.md#adding-a-new-translation) yourself - you only need to provide a handful of UI translation strings, as we automatically pull in the country names from the country-list project.
+If we don't currently support a language you need, it's easy to [contribute this](https://github.com/jackocnr/intl-tel-input/blob/master/.github/CONTRIBUTING.md#adding-a-new-translation) yourself - you only need to provide a handful of UI translation strings.
 
 ## Utilities Script
 The utilities script ([build/js/utils.js](build/js/utils.js)) is a custom build of Google's [libphonenumber](https://github.com/googlei18n/libphonenumber) which enables the following features: