react-native-phone-country-input 1.0.0

package/src/enum/CountryIds.ts

@@ -0,0 +1,256 @@
+export enum CountryId {
+    // Zone 1 - North American Numbering Plan (NANP)
+    UNITED_STATES = 'US',
+    CANADA = 'CA',
+    ANTIGUA_AND_BARBUDA = 'AG',
+    ANGUILLA = 'AI',
+    AMERICAN_SAMOA = 'AS',
+    BAHAMAS = 'BS',
+    BARBADOS = 'BB',
+    BERMUDA = 'BM',
+    BRITISH_VIRGIN_ISLANDS = 'VG',
+    CAYMAN_ISLANDS = 'KY',
+    DOMINICA = 'DM',
+    DOMINICAN_REPUBLIC = 'DO',
+    GRENADA = 'GD',
+    GUAM = 'GU',
+    JAMAICA = 'JM',
+    MONTSERRAT = 'MS',
+    NORTHERN_MARIANA_ISLANDS = 'MP',
+    PUERTO_RICO = 'PR',
+    SAINT_KITTS_AND_NEVIS = 'KN',
+    SAINT_LUCIA = 'LC',
+    SAINT_VINCENT_AND_THE_GRENADINES = 'VC',
+    SINT_MAARTEN = 'SX',
+    TRINIDAD_AND_TOBAGO = 'TT',
+    TURKS_AND_CAICOS_ISLANDS = 'TC',
+    UNITED_STATES_VIRGIN_ISLANDS = 'VI',
+    // Zone 2 - Africa
+    EGYPT = 'EG',
+    SOUTH_SUDAN = 'SS',
+    MOROCCO = 'MA',
+    WESTERN_SAHARA = 'EH',
+    ALGERIA = 'DZ',
+    TUNISIA = 'TN',
+    LIBYA = 'LY',
+    GAMBIA = 'GM',
+    SENEGAL = 'SN',
+    MAURITANIA = 'MR',
+    MALI = 'ML',
+    GUINEA = 'GN',
+    IVORY_COAST = 'CI',
+    BURKINA_FASO = 'BF',
+    NIGER = 'NE',
+    TOGO = 'TG',
+    BENIN = 'BJ',
+    MAURITIUS = 'MU',
+    LIBERIA = 'LR',
+    SIERRA_LEONE = 'SL',
+    GHANA = 'GH',
+    NIGERIA = 'NG',
+    CHAD = 'TD',
+    CENTRAL_AFRICAN_REPUBLIC = 'CF',
+    CAMEROON = 'CM',
+    CAPE_VERDE = 'CV',
+    SAO_TOME_AND_PRINCIPE = 'ST',
+    EQUATORIAL_GUINEA = 'GQ',
+    GABON = 'GA',
+    REPUBLIC_OF_THE_CONGO = 'CG',
+    DEMOCRATIC_REPUBLIC_OF_THE_CONGO = 'CD',
+    ANGOLA = 'AO',
+    GUINEA_BISSAU = 'GW',
+    BRITISH_INDIAN_OCEAN_TERRITORY = 'IO',
+    ASCENSION_ISLAND = 'AC',
+    SEYCHELLES = 'SC',
+    SUDAN = 'SD',
+    RWANDA = 'RW',
+    ETHIOPIA = 'ET',
+    SOMALIA = 'SO',
+    DJIBOUTI = 'DJ',
+    KENYA = 'KE',
+    TANZANIA = 'TZ',
+    UGANDA = 'UG',
+    BURUNDI = 'BI',
+    MOZAMBIQUE = 'MZ',
+    ZAMBIA = 'ZM',
+    MADAGASCAR = 'MG',
+    REUNION = 'RE',
+    MAYOTTE = 'YT',
+    ZIMBABWE = 'ZW',
+    NAMIBIA = 'NA',
+    MALAWI = 'MW',
+    LESOTHO = 'LS',
+    BOTSWANA = 'BW',
+    ESWATINI = 'SZ',
+    COMOROS = 'KM',
+    SOUTH_AFRICA = 'ZA',
+    SAINT_HELENA = 'SH',
+    ERITREA = 'ER',
+    ARUBA = 'AW',
+    FAROE_ISLANDS = 'FO',
+    GREENLAND = 'GL',
+    // Zone 3 - Europe
+    GREECE = 'GR',
+    NETHERLANDS = 'NL',
+    BELGIUM = 'BE',
+    FRANCE = 'FR',
+    SPAIN = 'ES',
+    GIBRALTAR = 'GI',
+    PORTUGAL = 'PT',
+    LUXEMBOURG = 'LU',
+    IRELAND = 'IE',
+    ICELAND = 'IS',
+    ALBANIA = 'AL',
+    MALTA = 'MT',
+    CYPRUS = 'CY',
+    FINLAND = 'FI',
+    ALAND_ISLANDS = 'AX',
+    BULGARIA = 'BG',
+    HUNGARY = 'HU',
+    LITHUANIA = 'LT',
+    LATVIA = 'LV',
+    ESTONIA = 'EE',
+    MOLDOVA = 'MD',
+    ARMENIA = 'AM',
+    BELARUS = 'BY',
+    ANDORRA = 'AD',
+    MONACO = 'MC',
+    SAN_MARINO = 'SM',
+    UKRAINE = 'UA',
+    SERBIA = 'RS',
+    MONTENEGRO = 'ME',
+    KOSOVO = 'XK',
+    CROATIA = 'HR',
+    SLOVENIA = 'SI',
+    BOSNIA_AND_HERZEGOVINA = 'BA',
+    NORTH_MACEDONIA = 'MK',
+    ITALY = 'IT',
+    VATICAN_CITY = 'VA',
+    ROMANIA = 'RO',
+    SWITZERLAND = 'CH',
+    CZECH_REPUBLIC = 'CZ',
+    SLOVAKIA = 'SK',
+    LIECHTENSTEIN = 'LI',
+    AUSTRIA = 'AT',
+    UNITED_KINGDOM = 'GB',
+    GUERNSEY = 'GG',
+    ISLE_OF_MAN = 'IM',
+    JERSEY = 'JE',
+    DENMARK = 'DK',
+    SWEDEN = 'SE',
+    NORWAY = 'NO',
+    SVALBARD_AND_JAN_MAYEN = 'SJ',
+    POLAND = 'PL',
+    GERMANY = 'DE',
+    // Zone 5 - Central & South America, Caribbean
+    FALKLAND_ISLANDS = 'FK',
+    SOUTH_GEORGIA_AND_THE_SOUTH_SANDWICH_ISLANDS = 'GS',
+    BELIZE = 'BZ',
+    GUATEMALA = 'GT',
+    EL_SALVADOR = 'SV',
+    HONDURAS = 'HN',
+    NICARAGUA = 'NI',
+    COSTA_RICA = 'CR',
+    PANAMA = 'PA',
+    SAINT_PIERRE_AND_MIQUELON = 'PM',
+    HAITI = 'HT',
+    PERU = 'PE',
+    MEXICO = 'MX',
+    CUBA = 'CU',
+    ARGENTINA = 'AR',
+    BRAZIL = 'BR',
+    CHILE = 'CL',
+    COLOMBIA = 'CO',
+    VENEZUELA = 'VE',
+    GUADELOUPE = 'GP',
+    SAINT_BARTHELEMY = 'BL',
+    SAINT_MARTIN = 'MF',
+    BOLIVIA = 'BO',
+    GUYANA = 'GY',
+    ECUADOR = 'EC',
+    FRENCH_GUIANA = 'GF',
+    PARAGUAY = 'PY',
+    MARTINIQUE = 'MQ',
+    SURINAME = 'SR',
+    URUGUAY = 'UY',
+    CURACAO = 'CW',
+    CARIBBEAN_NETHERLANDS = 'BQ',
+    // Zone 6 - Southeast Asia & Oceania
+    MALAYSIA = 'MY',
+    AUSTRALIA = 'AU',
+    CHRISTMAS_ISLAND = 'CX',
+    COCOS_KEELING_ISLANDS = 'CC',
+    INDONESIA = 'ID',
+    PHILIPPINES = 'PH',
+    NEW_ZEALAND = 'NZ',
+    PITCAIRN_ISLANDS = 'PN',
+    SINGAPORE = 'SG',
+    THAILAND = 'TH',
+    TIMOR_LESTE = 'TL',
+    NORFOLK_ISLAND = 'NF',
+    BRUNEI = 'BN',
+    NAURU = 'NR',
+    PAPUA_NEW_GUINEA = 'PG',
+    TONGA = 'TO',
+    SOLOMON_ISLANDS = 'SB',
+    VANUATU = 'VU',
+    FIJI = 'FJ',
+    PALAU = 'PW',
+    WALLIS_AND_FUTUNA = 'WF',
+    COOK_ISLANDS = 'CK',
+    NIUE = 'NU',
+    SAMOA = 'WS',
+    KIRIBATI = 'KI',
+    NEW_CALEDONIA = 'NC',
+    TUVALU = 'TV',
+    FRENCH_POLYNESIA = 'PF',
+    TOKELAU = 'TK',
+    MICRONESIA = 'FM',
+    MARSHALL_ISLANDS = 'MH',
+    // Zone 7 - Russia & Kazakhstan
+    RUSSIA = 'RU',
+    KAZAKHSTAN = 'KZ',
+    // Zone 8 - East Asia
+    JAPAN = 'JP',
+    SOUTH_KOREA = 'KR',
+    VIETNAM = 'VN',
+    NORTH_KOREA = 'KP',
+    HONG_KONG = 'HK',
+    MACAU = 'MO',
+    CAMBODIA = 'KH',
+    LAOS = 'LA',
+    CHINA = 'CN',
+    BANGLADESH = 'BD',
+    TAIWAN = 'TW',
+    // Zone 9 - South Asia, Middle East & Central Asia
+    TURKEY = 'TR',
+    INDIA = 'IN',
+    PAKISTAN = 'PK',
+    AFGHANISTAN = 'AF',
+    SRI_LANKA = 'LK',
+    MYANMAR = 'MM',
+    MALDIVES = 'MV',
+    LEBANON = 'LB',
+    JORDAN = 'JO',
+    SYRIA = 'SY',
+    IRAQ = 'IQ',
+    KUWAIT = 'KW',
+    SAUDI_ARABIA = 'SA',
+    YEMEN = 'YE',
+    OMAN = 'OM',
+    PALESTINIAN_TERRITORIES = 'PS',
+    UNITED_ARAB_EMIRATES = 'AE',
+    ISRAEL = 'IL',
+    BAHRAIN = 'BH',
+    QATAR = 'QA',
+    BHUTAN = 'BT',
+    MONGOLIA = 'MN',
+    NEPAL = 'NP',
+    IRAN = 'IR',
+    TAJIKISTAN = 'TJ',
+    TURKMENISTAN = 'TM',
+    AZERBAIJAN = 'AZ',
+    GEORGIA = 'GE',
+    KYRGYZSTAN = 'KG',
+    UZBEKISTAN = 'UZ',
+}

package/src/hooks/UsePhoneFieldState.tsx

@@ -0,0 +1,268 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { CountryCode } from '../consts/regions';
+import { CountryId } from '../enum/CountryIds';
+import { generateCountryCodeList } from '../utils/generateCountryCodeList';
+import { getDefaultRegion } from '../utils/getDefaultRegion';
+import { PhoneFieldOutcome } from '../PhoneNumberField';
+import { maskToPhoneNumber } from '../utils/maskToPhoneNumber';
+import { matchCountryCode } from '../utils/matchCountryCode';
+import Clipboard from '@react-native-clipboard/clipboard';
+import {
+  BACK_BUTTON,
+  CLEAR_BUTTON,
+  GLOBE_BUTTON,
+  KEYPAD_KEY,
+  SELECTION_TYPE,
+} from '../consts/KEYBOARD_LAYOUT';
+import { NativeSyntheticEvent, TextInputSelectionChangeEventData } from 'react-native';
+import { characterDeletion } from '../utils/characterDeletion';
+import { characterInsert } from '../utils/characterInsert';
+import { fromMaskedNumberToUnmaskedSelection } from '../utils/fromMaskedNumberToUnmaskedSelection';
+import { fromUnmaskedToMaskedPosition } from '../utils/fromUnmaskedToMaskedPosition';
+
+export interface usePhoneFieldStateParams {
+  allowedCountryCodes?: CountryId[] | null;
+  disallowedCountryCodes?: CountryId[] | null;
+}
+
+export interface usePhoneFieldStateReturn {
+  country?: CountryCode;
+  filteredCountryCodes?: CountryCode[];
+  phoneNumber?: string;
+  outcome?: PhoneFieldOutcome;
+  onChangeText: (phoneNumber: string) => void;
+  onChangeFlag: (newCountry: CountryCode) => void;
+  onKeyPress: (_key: KEYPAD_KEY) => void;
+  onCopy: () => void;
+  onPaste: () => Promise<boolean>;
+  isKeyboardOpen: boolean;
+  openKeyboard: () => void;
+  closeKeyboard: () => void;
+  isCountrySelectorOpen: boolean;
+  openCountrySelector: () => void;
+  closeCountrySelector: () => void;
+  onTextSelection: (e: NativeSyntheticEvent<TextInputSelectionChangeEventData>) => void;
+  onClearText: () => void;
+  cursorPosition: { start: number; end: number };
+}
+
+export function usePhoneFieldState({
+  allowedCountryCodes,
+  disallowedCountryCodes,
+}: usePhoneFieldStateParams): usePhoneFieldStateReturn {
+  const [country, setCountry] = useState<CountryCode | undefined>(undefined);
+  const [phoneNumber, setPhoneNumber] = useState<string | undefined>(undefined);
+  const phoneNumberRef = useRef(phoneNumber);
+  const [outcome, setOutcome] = useState<PhoneFieldOutcome | undefined>(undefined);
+  const [isKeyboardOpen, setIsKeyboardOpen] = useState(false);
+  const [cursorPosition, setCursorPosition] = useState<{ start: number; end: number }>({
+    start: 1,
+    end: 1,
+  });
+  const selectionRef = useRef<SELECTION_TYPE>({
+    start: 1,
+    end: 1,
+    hasBeenSelected: false,
+    hasBeenConsumed: true,
+  });
+
+  const openKeyboard = useCallback(() => setIsKeyboardOpen(true), []);
+  const closeKeyboard = useCallback(() => setIsKeyboardOpen(false), []);
+
+  const [isCountrySelectorOpen, setIsCountrySelectorOpen] = useState(false);
+  const openCountrySelector = useCallback(() => setIsCountrySelectorOpen(true), []);
+  const closeCountrySelector = useCallback(() => setIsCountrySelectorOpen(false), []);
+
+  const filteredCountryCodes = useMemo(() => {
+    return generateCountryCodeList(
+      allowedCountryCodes ?? undefined,
+      disallowedCountryCodes ?? undefined
+    );
+  }, [allowedCountryCodes, disallowedCountryCodes]);
+
+  const onChangeText = useCallback(
+    (_value: string) => {
+      const cleanedValue = _value.replace(/\D\s*/g, '').trim(); // remove non-digit characters
+
+      // parse the country code from the phone number and set the country state
+      let matchedCountry = matchCountryCode(filteredCountryCodes, cleanedValue);
+      console.debug('matchedCountry', matchedCountry);
+      setCountry(matchedCountry || undefined);
+
+      if (!!matchedCountry && cleanedValue.length >= 2) {
+        // apply masking to the phone number based on the matched country code
+        const output = maskToPhoneNumber(
+          cleanedValue,
+          matchedCountry?.code.replace('+', ''),
+          matchedCountry?.mask
+        );
+        setPhoneNumber(output);
+        phoneNumberRef.current = output;
+        const ouputWthOutMask = output.replace(/\D/g, '');
+        console.debug(output, ouputWthOutMask);
+
+        const correctLength = (matchedCountry.code + matchedCountry.mask).length;
+        const expectedDigitCount =
+          matchedCountry.code.replace(/\D/g, '').length +
+          matchedCountry.mask.replace(/[^#]/g, '').length;
+        setOutcome({
+          countryDetails: matchedCountry || null,
+          phoneNumber: ouputWthOutMask,
+          isValid: ouputWthOutMask.length === expectedDigitCount,
+          correctLength,
+        });
+      } else {
+        setPhoneNumber(cleanedValue);
+        phoneNumberRef.current = cleanedValue;
+        const correctLength = ((matchedCountry?.code ?? '') + (matchedCountry?.mask ?? '')).length;
+        setOutcome({
+          countryDetails: matchedCountry || null,
+          phoneNumber: cleanedValue,
+          isValid: false,
+          correctLength,
+        });
+      }
+    },
+    [filteredCountryCodes]
+  );
+
+  const onClearText = useCallback(() => {
+    console.debug('Refreshing....');
+    if (!outcome) {
+      console.error('Outcome is not defined, so cannot clear text');
+      return;
+    }
+    const current_outcome = outcome;
+    setPhoneNumber(current_outcome?.countryDetails?.code);
+    phoneNumberRef.current = current_outcome?.countryDetails?.code;
+
+    setOutcome({ ...current_outcome, phoneNumber: current_outcome?.countryDetails?.code ?? '' });
+  }, [outcome]);
+
+  const onChangeFlag = useCallback((newCountry: CountryCode) => {
+    const _phoneNumber = newCountry.code.replace('+', '');
+
+    setOutcome({
+      countryDetails: newCountry,
+      phoneNumber: _phoneNumber,
+      isValid: false,
+      correctLength: (newCountry.code + newCountry.mask).length,
+    });
+    setPhoneNumber(_phoneNumber);
+    phoneNumberRef.current = _phoneNumber;
+    setCountry(newCountry);
+
+    const newMasked = '+' + _phoneNumber;
+    const unmaskedEnd = _phoneNumber.replace(/\D/g, '').length;
+    selectionRef.current = {
+      start: unmaskedEnd,
+      end: unmaskedEnd,
+      hasBeenSelected: true,
+      hasBeenConsumed: false,
+    };
+    const maskedEnd = fromUnmaskedToMaskedPosition(newMasked, unmaskedEnd);
+    setCursorPosition({ start: maskedEnd, end: maskedEnd });
+  }, []);
+
+  const onKeyPress = useCallback(
+    (_key: KEYPAD_KEY) => {
+      const current = phoneNumberRef.current;
+      const existing_number = '+' + (current ?? '').replace(/\D/g, '');
+      const { start, end } = selectionRef.current;
+
+      if (_key.main === BACK_BUTTON) {
+        const isRange = start !== end;
+        if (start > 0 || isRange) {
+          const outcome = characterDeletion(existing_number, selectionRef.current);
+          onChangeText(outcome);
+          if (start > 0) {
+            selectionRef.current = { start: start - 1, end: start - 1, hasBeenSelected: true };
+          }
+        }
+      } else if (_key.main === CLEAR_BUTTON) {
+        onChangeText('');
+        selectionRef.current = { start: 0, end: 0, hasBeenSelected: false };
+      } else if (_key.main === GLOBE_BUTTON) {
+        openCountrySelector();
+      } else {
+        const outcome = characterInsert(existing_number, _key.main, selectionRef.current);
+        onChangeText(outcome);
+        if (phoneNumberRef.current && selectionRef.current.start < phoneNumberRef.current.length) {
+          selectionRef.current = { start: start + 1, end: start + 1, hasBeenSelected: true };
+        }
+      }
+
+      const newMasked = '+' + (phoneNumberRef.current ?? '');
+      const maskedStart = fromUnmaskedToMaskedPosition(newMasked, selectionRef.current.start);
+      setCursorPosition({ start: maskedStart, end: maskedStart });
+    },
+    [onChangeText, openCountrySelector]
+  );
+
+  const onCopy = useCallback(async () => {
+    console.debug('copying phone number: ', outcome?.phoneNumber);
+    Clipboard.setString(outcome?.phoneNumber ?? '');
+  }, [outcome?.phoneNumber]);
+
+  const onPaste = useCallback(async (): Promise<boolean> => {
+    const clipBoardContents = (await Clipboard.getString()).trim();
+    if (clipBoardContents.replace(/\D\s*/g, '').length < 1) {
+      return false;
+    }
+    onChangeText(clipBoardContents);
+    const newMasked = '+' + (phoneNumberRef.current ?? '');
+    const unmaskedEnd = (phoneNumberRef.current ?? '').replace(/\D/g, '').length;
+    selectionRef.current = {
+      start: unmaskedEnd,
+      end: unmaskedEnd,
+      hasBeenSelected: true,
+      hasBeenConsumed: false,
+    };
+    const maskedEnd = fromUnmaskedToMaskedPosition(newMasked, unmaskedEnd);
+    setCursorPosition({ start: maskedEnd, end: maskedEnd });
+    return true;
+  }, [onChangeText]);
+
+  const onTextSelection = useCallback(
+    (e: NativeSyntheticEvent<TextInputSelectionChangeEventData>) => {
+      const next = e.nativeEvent.selection;
+      // Include '+' so maskedPoint indexes align with the displayed string
+      const maskedValue = '+' + (phoneNumberRef.current ?? '');
+      const start = fromMaskedNumberToUnmaskedSelection(maskedValue, next.start);
+      const end = fromMaskedNumberToUnmaskedSelection(maskedValue, next.end);
+      selectionRef.current = { start, end, hasBeenSelected: true, hasBeenConsumed: false };
+      setCursorPosition({ start: next.start, end: next.end });
+    },
+    []
+  );
+
+  useEffect(() => {
+    const defaultRegion = getDefaultRegion(filteredCountryCodes);
+    console.debug(defaultRegion);
+    setCountry(defaultRegion);
+    onChangeText(defaultRegion?.code ?? ''); // set the default country code in the input field on load
+
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return {
+    country,
+    filteredCountryCodes,
+    phoneNumber,
+    outcome,
+    onChangeText,
+    onChangeFlag,
+    onKeyPress,
+    onCopy,
+    onPaste,
+    isKeyboardOpen,
+    openKeyboard,
+    closeKeyboard,
+    isCountrySelectorOpen,
+    openCountrySelector,
+    closeCountrySelector,
+    onTextSelection,
+    onClearText,
+    cursorPosition,
+  };
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+// Opinionated all-in-one component
+export { PhoneCountryInput } from './PhoneCountryInput/PhoneCountryInput';
+export type { PhoneCountryInputProps } from './PhoneCountryInput/PhoneCountryInput';
+
+// Individual pieces
+export { PhoneNumberField } from './PhoneNumberField';
+export type { PhoneNumberFieldProps, PhoneFieldOutcome } from './PhoneNumberField';
+
+export { CountrySelector } from './CountrySelector/CountrySelector';
+export type { CountrySelectorProps } from './CountrySelector/CountrySelector';
+
+export { CountrySelectorModal } from './CountrySelector/CountrySelectorModal';
+export type { CountrySelectorModalProps } from './CountrySelector/CountrySelectorModal';
+
+export { default as Keyboard } from './Keyboard/Keyboard';
+export type { KeyboardProps, PasteErrorModalProps, CopySuccessModalProps } from './Keyboard/Keyboard';
+
+// State management hook
+export { usePhoneFieldState } from './hooks/UsePhoneFieldState';
+export type {
+  usePhoneFieldStateParams,
+  usePhoneFieldStateReturn,
+} from './hooks/UsePhoneFieldState';
+
+// Types for advanced users
+export type { CountryCode } from './consts/regions';
+export { CountryId } from './enum/CountryIds';

package/src/utils/characterDeletion.ts

@@ -0,0 +1,16 @@
+import { SELECTION_TYPE } from '../consts/KEYBOARD_LAYOUT';
+
+export function characterDeletion(phoneNumber: string, selection: SELECTION_TYPE): string {
+  const isRange = selection.start !== selection.end;
+
+  if (!selection.hasBeenSelected && !isRange && selection.start === 0) {
+    return phoneNumber.slice(0, -1);
+  }
+  if (isRange) {
+    // selection.start digits are before the selection; first selected char is at index start+1
+    return phoneNumber.slice(0, selection.start + 1) + phoneNumber.slice(selection.end + 1);
+  }
+  // backspace: delete the digit immediately to the left of cursor (at index start); clamp to protect '+'
+  const start = Math.max(selection.start, 1);
+  return phoneNumber.slice(0, start) + phoneNumber.slice(start + 1);
+}

package/src/utils/characterInsert.ts

@@ -0,0 +1,20 @@
+import { SELECTION_TYPE } from '../consts/KEYBOARD_LAYOUT';
+
+export function characterInsert(
+  phoneNumber: string,
+  newChar: string,
+  selection: SELECTION_TYPE
+): string {
+  const isARange = selection.start !== selection.end;
+
+  if (isARange) {
+    // selection.start digits are before the selection; first selected char is at index start+1
+    return phoneNumber.slice(0, selection.start + 1) + newChar + phoneNumber.slice(selection.end + 1);
+  } else if (selection.start === 0 && !selection.hasBeenSelected) {
+    return phoneNumber + newChar;
+  } else {
+    // cursor is after `start` digits; insert before char at index start+1; clamp to protect '+'
+    const start = Math.max(selection.start, 1);
+    return phoneNumber.slice(0, start + 1) + newChar + phoneNumber.slice(start + 1);
+  }
+}

package/src/utils/fromMaskedNumberToUnmaskedSelection.ts

@@ -0,0 +1,10 @@
+export function fromMaskedNumberToUnmaskedSelection(
+  maskedValue: string,
+  maskedPoint: number
+): number {
+  let count = 0;
+  for (let i = 0; i < maskedPoint && i < maskedValue.length; i++) {
+    if (/\d/.test(maskedValue[i])) count++;
+  }
+  return count;
+}

package/src/utils/fromUnmaskedToMaskedPosition.ts

@@ -0,0 +1,13 @@
+export function fromUnmaskedToMaskedPosition(maskedValue: string, unmaskedPos: number): number {
+  if (unmaskedPos <= 0) return 1;
+  let digitCount = 0;
+  for (let i = 0; i < maskedValue.length; i++) {
+    if (/\d/.test(maskedValue[i])) {
+      digitCount++;
+      if (digitCount === unmaskedPos) {
+        return i + 1;
+      }
+    }
+  }
+  return maskedValue.length;
+}

package/src/utils/generateCountryCodeList.ts

@@ -0,0 +1,22 @@
+import { countryCodeList } from '../consts/regions';
+import { CountryId } from '../enum/CountryIds';
+
+export function generateCountryCodeList(
+  allowedCountryCodes?: CountryId[],
+  disallowedCountryCodes?: CountryId[]
+) {
+  return (
+    countryCodeList
+      .filter(({ id }) => {
+        if (allowedCountryCodes && !allowedCountryCodes.includes(id)) {
+          return false;
+        }
+        if (disallowedCountryCodes && disallowedCountryCodes.includes(id)) {
+          return false;
+        }
+        return true;
+      })
+      // sort by longer country codes first to ensure that we match the most specific country code when parsing the phone number
+      .sort((a, b) => b.code.length - a.code.length)
+  );
+}

package/src/utils/getDefaultRegion.ts

@@ -0,0 +1,30 @@
+import { getLocales } from 'expo-localization';
+import { CountryCode } from '../consts/regions';
+
+export function getDefaultRegion(filteredCountryCodes: CountryCode[]): CountryCode {
+  const localization = getLocales();
+  // console.debug('localization', JSON.stringify(localization, null, 2));
+  const id = localization?.[0]?.regionCode;
+  if (id) {
+    const matchedCountry = filteredCountryCodes.find((country) => country.id === id);
+    if (matchedCountry) {
+      return matchedCountry;
+    }
+  }
+  return filteredCountryCodes[0];
+}
+
+export function getDefaultRegionWithNullableState(
+  filteredCountryCodes: CountryCode[]
+): CountryCode | null {
+  const localization = getLocales();
+  // console.debug('localization', JSON.stringify(localization, null, 2));
+  const id = localization?.[0]?.regionCode;
+  if (id) {
+    const matchedCountry = filteredCountryCodes.find((country) => country.id === id);
+    if (matchedCountry) {
+      return matchedCountry;
+    }
+  }
+  return null;
+}