From 557cbf500554ea101aa337e21b539d7060de30be Mon Sep 17 00:00:00 2001 From: Rob Brackett Date: Thu, 3 Oct 2024 14:29:30 -0700 Subject: [PATCH] Rename `utilsScript` to `loadUtilsOnInit` --- README.md | 39 +++++++++++-------- build/js/intlTelInput.d.ts | 2 + build/js/intlTelInput.js | 14 +++++-- build/js/intlTelInput.min.js | 2 +- build/js/intlTelInputWithUtils.js | 14 +++++-- build/js/intlTelInputWithUtils.min.js | 2 +- demo.html | 2 +- react/build/IntlTelInput.cjs | 14 +++++-- react/build/IntlTelInput.d.ts | 2 + react/build/IntlTelInput.js | 14 +++++-- react/build/IntlTelInputWithUtils.cjs | 14 +++++-- react/build/IntlTelInputWithUtils.js | 14 +++++-- react/demo/set-number/set-number-bundle.js | 14 +++++-- react/demo/simple/simple-bundle.js | 14 +++++-- .../toggle-disabled/toggle-disabled-bundle.js | 14 +++++-- react/demo/validation/validation-bundle.js | 14 +++++-- spec.html | 4 +- src/js/intl-tel-input.ts | 19 +++++++-- .../{utilsScript.js => loadUtilsOnInit.js} | 26 ++++++------- src/spec/tests/static/loadUtils.js | 16 ++++---- vue/build/IntlTelInput.mjs | 20 +++++----- vue/build/IntlTelInputWithUtils.mjs | 14 ++++--- 22 files changed, 186 insertions(+), 102 deletions(-) rename src/spec/tests/options/{utilsScript.js => loadUtilsOnInit.js} (82%) diff --git a/README.md b/README.md index 2acc34c66..f88eff583 100644 --- a/README.md +++ b/README.md @@ -83,7 +83,7 @@ _Note: We have now dropped support for all versions of Internet Explorer because ``` @@ -109,18 +109,18 @@ _Note: We have now dropped support for all versions of Internet Explorer because const input = document.querySelector("#phone"); intlTelInput(input, { - utilsScript: () => import("intl-tel-input/utils") + loadUtilsOnInit: () => import("intl-tel-input/utils") }); ``` -Most bundlers (such as Webpack, Vite, or Parcel) will see this and place the [utilities script](#utilities-script) in a separate bundle and load it asynchronously, only when needed. If this doesn’t work with your bundler or you want to load the utils module from some other location (such as a CDN) you can set the `utilsScript` option to the URL to load from as a string. For example: +Most bundlers (such as Webpack, Vite, or Parcel) will see this and place the [utilities script](#utilities-script) in a separate bundle and load it asynchronously, only when needed. If this doesn’t work with your bundler or you want to load the utils module from some other location (such as a CDN) you can set the `loadUtilsOnInit` option to the URL to load from as a string. For example: ```js import intlTelInput from 'intl-tel-input'; const input = document.querySelector("#phone"); intlTelInput(input, { - utilsScript: `https://cdn.jsdelivr.net/npm/intl-tel-input@${intlTelInput.version}/build/js/utils.js`; + loadUtilsOnInit: `https://cdn.jsdelivr.net/npm/intl-tel-input@${intlTelInput.version}/build/js/utils.js`; }); ``` @@ -148,7 +148,7 @@ intlTelInput(input, { ``` @@ -315,6 +315,15 @@ intlTelInput(input, { Type: `String` Default: `""` Set the initial country selection by specifying its country code e.g. `"us"` for the United States. (Be careful not to do this unless you are sure of the user's country, as it can lead to tricky issues if set incorrectly and the user auto-fills their national number and submits the form without checking - in certain cases, this can pass validation and you can end up storing a number with the wrong dial code). You can also set `initialCountry` to `"auto"`, which will look up the user's country based on their IP address (requires the `geoIpLookup` option - [see example](https://intl-tel-input.com/examples/lookup-country.html)). Note that however you use `initialCountry`, it will not update the country selection if the input already contains a number with an international dial code. +**loadUtilsOnInit** +Type: `String` or `() => Promise` Default: `""` Example: `"/build/js/utils.js"` + +This is one way to (lazy) load the included utils.js (to enable formatting/validation etc) - see [Loading The Utilities Script](#loading-the-utilities-script) for more options. You will need to host the [utils.js](https://github.com/jackocnr/intl-tel-input/blob/master/build/js/utils.js) file, and then set the `loadUtilsOnInit` option to that URL, or alternatively just point it to a CDN hosted version e.g. `"https://cdn.jsdelivr.net/npm/intl-tel-input@24.5.2/build/js/utils.js"`. The script is loaded via a [dynamic import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) statement, which means the URL cannot be relative - it must be absolute. + +Alternatively, this can be a function that returns a promise for the utils module. When using a bundler like Webpack, this can be used to tell the bundler that the utils script should be kept in a separate file from the rest of your code. For example: `{ loadUtilsOnInit: () => import("intl-tel-input/utils") }`. + +The script is only fetched when you initialise the plugin, and additionally, only when the page has finished loading (on the window load event) to prevent blocking (the script is ~260KB). When instantiating the plugin, a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) object is returned under the `promise` instance property, so you can do something like `iti.promise.then(callback)` to know when initialisation requests like this have finished. See [Utilities Script](#utilities-script) for more information. + **nationalMode** Type: `Boolean` Default: `true` Format numbers in the national format, rather than the international format. This applies to placeholder numbers, and when displaying users' existing numbers. Note that it's fine for users to type their numbers in national format - as long as they have selected the right country, you can use `getNumber` to extract a full international number - [see example](https://intl-tel-input.com/examples/national-mode.html). It is recommended to leave this option enabled, to encourage users to enter their numbers in national format as this is usually more familiar to them and so it creates a better user experience. @@ -345,14 +354,10 @@ As the user types in the input, ignore any irrelevant characters. The user can o 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 `").appendTo("body"); iti2 = window.intlTelInput(input2[0], { - utilsScript: "test/url/three/utils.js", + loadUtilsOnInit: "test/url/three/utils.js", }); }); @@ -136,14 +136,14 @@ describe("loadUtils:", function() { - describe("force documentReady=true then init plugin with utilsScript", function() { + describe("force documentReady=true then init plugin with loadUtilsOnInit", function() { var url3 = "/build/js/utils.js?v=3"; beforeEach(function() { window.intlTelInput.documentReady = () => true; iti = window.intlTelInput(input[0], { - utilsScript: url3, + loadUtilsOnInit: url3, }); }); diff --git a/vue/build/IntlTelInput.mjs b/vue/build/IntlTelInput.mjs index f8a403dad..7199c038e 100644 --- a/vue/build/IntlTelInput.mjs +++ b/vue/build/IntlTelInput.mjs @@ -1,4 +1,4 @@ -import { mergeModels as D, useModel as x, ref as v, onMounted as E, watch as M, onUnmounted as F, withDirectives as B, openBlock as O, createElementBlock as V, mergeProps as z, vModelText as R } from "vue"; +import { mergeModels as D, useModel as x, ref as v, onMounted as E, watch as M, onUnmounted as O, withDirectives as F, openBlock as B, createElementBlock as V, mergeProps as z, vModelText as R } from "vue"; const N = [ [ "af", @@ -1607,6 +1607,8 @@ const T = { i18n: {}, //* Initial country. initialCountry: "", + //* Specify the path to the libphonenumber script to enable validation/formatting. + loadUtilsOnInit: "", //* National vs international formatting for numbers e.g. placeholders and displaying existing numbers. nationalMode: !0, //* Display only these countries. @@ -1627,7 +1629,7 @@ const T = { navigator.userAgent ) || window.innerWidth <= 500 ) : !1, - //* Specify the path to the libphonenumber script to enable validation/formatting. + //* Deprecated! Use `loadUtilsOnInit` instead. utilsScript: "", //* The number type to enforce during validation. validationNumberType: "MOBILE" @@ -1936,12 +1938,12 @@ class G { } //* Init many requests: utils script / geo ip lookup. _initRequests() { - const { utilsScript: t, initialCountry: e, geoIpLookup: i } = this.options; - t && !l.utils ? (this._handlePageLoad = () => { - var n; - window.removeEventListener("load", this._handlePageLoad), (n = l.loadUtils(t)) == null || n.catch(() => { + let { loadUtilsOnInit: t, utilsScript: e, initialCountry: i, geoIpLookup: s } = this.options; + !t && e && (console.warn("intl-tel-input: The `utilsScript` option is deprecated and will be removed in a future release! Please use the `loadUtilsOnInit` option instead."), t = e), t && !l.utils ? (this._handlePageLoad = () => { + var o; + window.removeEventListener("load", this._handlePageLoad), (o = l.loadUtils(t)) == null || o.catch(() => { }); - }, l.documentReady() ? this._handlePageLoad() : window.addEventListener("load", this._handlePageLoad)) : this.resolveUtilsScriptPromise(), e === "auto" && i && !this.selectedCountryData.iso2 ? this._loadAutoCountry() : this.resolveAutoCountryPromise(); + }, l.documentReady() ? this._handlePageLoad() : window.addEventListener("load", this._handlePageLoad)) : this.resolveUtilsScriptPromise(), i === "auto" && s && !this.selectedCountryData.iso2 ? this._loadAutoCountry() : this.resolveAutoCountryPromise(); } //* Perform the geo ip lookup. _loadAutoCountry() { @@ -2557,10 +2559,10 @@ const W = (u) => { var m; return (m = a.value) == null ? void 0 : m.setDisabled(h); } - ), F(() => { + ), O(() => { var h; return (h = a.value) == null ? void 0 : h.destroy(); - }), t({ instance: a, input: o }), (h, m) => B((O(), V("input", z({ + }), t({ instance: a, input: o }), (h, m) => F((B(), V("input", z({ ref_key: "input", ref: o, "onUpdate:modelValue": m[0] || (m[0] = (f) => i.value = f), diff --git a/vue/build/IntlTelInputWithUtils.mjs b/vue/build/IntlTelInputWithUtils.mjs index 7d0727b45..d4ca8900b 100644 --- a/vue/build/IntlTelInputWithUtils.mjs +++ b/vue/build/IntlTelInputWithUtils.mjs @@ -1607,6 +1607,8 @@ const u2 = { i18n: {}, //* Initial country. initialCountry: "", + //* Specify the path to the libphonenumber script to enable validation/formatting. + loadUtilsOnInit: "", //* National vs international formatting for numbers e.g. placeholders and displaying existing numbers. nationalMode: !0, //* Display only these countries. @@ -1627,7 +1629,7 @@ const u2 = { navigator.userAgent ) || window.innerWidth <= 500 ) : !1, - //* Specify the path to the libphonenumber script to enable validation/formatting. + //* Deprecated! Use `loadUtilsOnInit` instead. utilsScript: "", //* The number type to enforce during validation. validationNumberType: "MOBILE" @@ -1936,12 +1938,12 @@ class F2 { } //* Init many requests: utils script / geo ip lookup. _initRequests() { - const { utilsScript: e, initialCountry: i, geoIpLookup: n } = this.options; - e && !m.utils ? (this._handlePageLoad = () => { - var a; - window.removeEventListener("load", this._handlePageLoad), (a = m.loadUtils(e)) == null || a.catch(() => { + let { loadUtilsOnInit: e, utilsScript: i, initialCountry: n, geoIpLookup: o } = this.options; + !e && i && (console.warn("intl-tel-input: The `utilsScript` option is deprecated and will be removed in a future release! Please use the `loadUtilsOnInit` option instead."), e = i), e && !m.utils ? (this._handlePageLoad = () => { + var c; + window.removeEventListener("load", this._handlePageLoad), (c = m.loadUtils(e)) == null || c.catch(() => { }); - }, m.documentReady() ? this._handlePageLoad() : window.addEventListener("load", this._handlePageLoad)) : this.resolveUtilsScriptPromise(), i === "auto" && n && !this.selectedCountryData.iso2 ? this._loadAutoCountry() : this.resolveAutoCountryPromise(); + }, m.documentReady() ? this._handlePageLoad() : window.addEventListener("load", this._handlePageLoad)) : this.resolveUtilsScriptPromise(), n === "auto" && o && !this.selectedCountryData.iso2 ? this._loadAutoCountry() : this.resolveAutoCountryPromise(); } //* Perform the geo ip lookup. _loadAutoCountry() {