intl-tel-input-options.ts

/**
 * Shamefully extracted from :
 * https://github.com/DefinitelyTyped/DefinitelyTyped/blob/fda699244c8d6de167e57dd6f5e901e617e5a7b5/types/intl-tel-input/index.d.ts
 *
 * Because the typings target JQuery.
 *
 * Definitions by:
 *      Fidan Hakaj <https://github.com/fdnhkj>,
 *      Leonard Thieu <https://github.com/leonard-thieu>,
 *      Márton Molnár <https://github.com/molnarm>
 *
 * Hope I did not forget crediting someone...
 *
 * Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
 */
export interface IntlTelInputOptions {
    /**
     * Whether or not to allow the dropdown. If disabled, there is no dropdown
     * arrow, and the selected flag is not clickable. Also we display the
     * selected flag on the right instead because it is just a marker of state.
     * Default = true
     */
    allowDropdown?: boolean;
    /**
     * If there is just a dial code in the input: remove it on blur or submit,
     * and re-add it on focus. This is to prevent just a dial code getting
     * submitted with the form. Requires nationalMode to be set to false.
     * Default = true
     */
    autoHideDialCode?: boolean;
    /**
     * Set the input's placeholder to an example number for the selected country, and update it if the country changes.
     * You can specify the number type using the placeholderNumberType option.
     * By default it is set to "polite", which means it will only set the placeholder if the input doesn't already have one.
     * You can also set it to "aggressive", which will replace any existing placeholder, or "off".
     * Requires the utilsScript option.
     * Default = "polite"
     */
    autoPlaceholder?: 'off' | 'polite' | 'aggressive';
    /**
     * Add a search input to the top of the dropdown, so users can filter the displayed countries.
     * Default = true
     */
    countrySearch?: boolean;
    /**
     * Change the placeholder generated by autoPlaceholder. Must return a string.
     * Default = null
     */
    customPlaceholder?: (selectedCountryPlaceholder: string, selectedCountryData: CountryData) => string;
    /**
     * Expects a node e.g. document.body. Instead of putting the country dropdown next to the input,
     * append it to the specified node, and it will then be positioned absolutely next to the input using JavaScript.
     * This is useful when the input is inside a container with overflow: hidden.
     * Note that the absolute positioning can be broken by scrolling, so it will automatically close on the window scroll event.
     * Default = null
     */
    dropdownContainer?: Node;
    /**
     * In the dropdown, display all countries except the ones you specify here.
     * Default = null
     */
    excludeCountries?: string[];
    /**
     * Format the input value (according to the nationalMode option) during initialisation, and on setNumber.
     * Requires the utilsScript option.
     * Default = true
     */
    formatOnDisplay?: boolean;
    /**
     * When setting initialCountry to "auto", you must use this option to
     * specify a custom function that looks up the user's location,
     * and then calls the success callback with the relevant country code.
     * Also note that when instantiating the plugin, if the Promise object is defined,
     * one of those 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 completed.
     * Default = null
     */
    geoIpLookup?: (callback: (countryCode: string) => void) => void;
    /**
     * Add a hidden input with the given name (or if your input name contains square brackets then it will give the
     * hidden input the same name, replacing the contents of the brackets with the given name). On submit, populate it
     * with the full international number (using getNumber). This is a quick way for people using non-ajax forms to get
     * the full international number, even when nationalMode is enabled.
     * Note: requires the input to be inside a form element, as this feature works by listening for the submit event on
     * the closest form element. Also note that since this uses getNumber internally, it expects a valid number, and so
     * should only be used after validation.
     * Default = ""
     */
    hiddenInput?: string;
    /**
     * Set the initial country selection by specifying it's country code.
     * You can also set it to "auto", which will lookup the user's country based
     * on their IP address (requires the geoIpLookup option).
     * Note that the "auto" option will not update the country selection if the
     * input already contains a number. If you leave initialCountry blank,
     * it will default to the first country in the list.
     */
    initialCountry?: string;
    /**
     * Allows to translate the countries by its given iso code e.g.:
     * { 'de': 'Deutschland' }
     */
    i18n?: { [key: string]: string };
    /**
     * Allow users to enter national numbers (and not have to think about
     * international dial codes). Formatting, validation and placeholders still
     * work. Then you can use getNumber to extract a full international number.
     * This option now defaults to true, and it is recommended that you leave it
     * that way as it provides a better experience for the user.
     * Default = true
     */
    nationalMode?: boolean;
    /**
     * In the dropdown, display only the countries you specify.
     * Default = undefined
     */
    onlyCountries?: string[];
    /**
     * Specify one of the keys from the global enum intlTelInputUtils.numberType
     * e.g. "FIXED_LINE" to set the number type to use for the placeholder.
     * Default = MOBILE
     */
    placeholderNumberType?: placeholderNumberType;
    /**
     * Specify the countries to appear at the top of the list.
     * Note that this option is not compatible with the countrySearch feature, and so that needs to be disabled for this to work.
     */
    preferredCountries?: string[];
    /**
     * Display the country dial code next to the selected flag so it's not part
     * of the typed number. Note that this will disable nationalMode because
     * technically we are dealing with international numbers, but with the
     * dial code separated.
     * Default = false
     */
    showSelectedDialCode?: boolean;
    /**
     * Enable formatting/validation etc. by specifying the URL of the included utils.js script
     * (or alternatively just point it to the file on cdnjs.com). The script is fetched when the page has finished
     * loading (on the window load event) to prevent blocking (the script is ~215KB). When instantiating the plugin, if
     * the Promise object is defined, one of those 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.
     * Note that if you're lazy loading the plugin script itself (intlTelInput.js)
     * this will not work and you will need to use the loadUtils method instead.
     * Example: "build/js/utils.js"
     * Default = ""
     */
    utilsScript?: string;
}

export interface CountryData {
    name: string;
    iso2: string;
    dialCode: string;
}

export type placeholderNumberType =
    | 'FIXED_LINE_OR_MOBILE'
    | 'FIXED_LINE'
    | 'MOBILE'
    | 'PAGER'
    | 'PERSONAL_NUMBER'
    | 'PREMIUM_RATE'
    | 'SHARED_COST'
    | 'TOLL_FREE'
    | 'UAN'
    | 'UNKNOWN'
    | 'VOICEMAIL'
    | 'VOIP';