feat: typescript support (patw0929#389)

* build(npm): add TypeScript 4.3.5 w/ basic project setup

* feat(types): add module definitions

* feat(types): use jQuery for underscore.deferred

According underscore.deferred's author, its API is very similar to jQuery's Deferred.

* test(types): check definitions

The .d.ts files aren't tested in jest. We’ll have to use tsd instead.

* build(types): add definition file copy operation

The tsc command won't help us here, but this will.

- Manual copy: https://stackoverflow.com/a/56440335
- Script args: https://apple.stackexchange.com/a/228045

Using gulp hasn't been considered due to dependency bloat.

* refactor(npm): split build script into readable fragments

For easier maintenance.

* chore(lint): add TypeScript configs

* docs(readme): mention TypeScript support

Author: andrewsantarin

.eslintrc.js

@@ -75,12 +75,68 @@ module.exports = {
     ],
     'no-plusplus': ['error', { allowForLoopAfterthoughts: true }],
   },
-
   globals: {
     __DEVELOPMENT__: true,
     __CLIENT__: true,
     __SERVER__: true,
     __DISABLE_SSR__: true,
     __DEVTOOLS__: true,
   },
+  overrides: [
+    // typescript .d.ts config
+    {
+      extends: [
+        'eslint:recommended',
+        'plugin:@typescript-eslint/eslint-recommended',
+        'plugin:@typescript-eslint/recommended',
+      ],
+      files: ['**/*.d.ts'],
+      parser: '@typescript-eslint/parser',
+      plugins: [
+        '@typescript-eslint',
+        'eslint-plugin-import',
+        'eslint-plugin-react',
+      ],
+      rules: {
+        '@typescript-eslint/explicit-module-boundary-types': 'off',
+        '@typescript-eslint/no-explicit-any': 'off',
+        '@typescript-eslint/no-empty-interface': 'off',
+        'import/order': [
+          'error',
+          {
+            alphabetize: {
+              order: 'asc',
+            },
+            groups: [['external', 'builtin'], 'parent', 'sibling'],
+            'newlines-between': 'always',
+          },
+        ],
+        'react/sort-comp': [
+          2,
+          {
+            order: [
+              'static-methods',
+              'instance-variables',
+              'instance-methods',
+              'lifecycle',
+              'everything-else',
+              'render',
+            ],
+          },
+        ],
+        'spaced-comment': [
+          'error',
+          'always',
+          {
+            line: {
+              markers: ['#region', '#endregion', 'region', 'endregion'],
+            },
+          },
+        ],
+      },
+      settings: {
+        'import/resolver': 'eslint-import-resolver-typescript',
+      },
+    },
+  ],
 }

README.md

@@ -40,8 +40,15 @@ Then open [`localhost:3000`](http://localhost:3000) in a browser.
 yarn add react-intl-tel-input
 ```
 
+
+### TypeScript
+
+`react-intl-tel-input` ships with official type declarations out of the box.
+
+
 ## Usage
 
+### JavaScript
 ```javascript
 import IntlTelInput from 'react-intl-tel-input';
 import 'react-intl-tel-input/dist/main.css';
@@ -52,6 +59,40 @@ import 'react-intl-tel-input/dist/main.css';
 />
 ```
 
+### TypeScript
+```tsx
+import * as IntlTelInput from 'react-intl-tel-input';
+import 'react-intl-tel-input/dist/main.css';
+
+<IntlTelInput
+  containerClassName="intl-tel-input"
+  inputClassName="form-control"
+/>
+```
+
+If your `tsconfig.json` contains the following config:
+
+**tsconfig.json**
+```json
+{
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+  }
+}
+```
+
+... use the default import workflow instead:
+```tsx
+import IntlTelInput from 'react-intl-tel-input';
+import 'react-intl-tel-input/dist/main.css';
+
+<IntlTelInput
+  containerClassName="intl-tel-input"
+  inputClassName="form-control"
+/>
+```
+
 ### Properties
 
 Please see the [Demo Page](https://patw0929.github.io/react-intl-tel-input/)
@@ -67,11 +108,13 @@ You can prepare a distribution build using `yarn build`.
 
 Any kind of contribution including proposals, doc improvements, enhancements, bug fixes are always welcome. 
 
-To contribute to react-intl-tel-input, clone this repo locally and commit your code on a separate branch. Please write tests for your code, and run the linter before opening a pull-request:
+To contribute to `react-intl-tel-input`, clone this repo locally and commit your code on a separate branch. Please write tests for your code, and run the linter before opening a pull-request:
 
-```
-yarn test
-yarn run lint
+```bash
+yarn test    # if you are enhancing the JavaScript modules
+yarn test:ts # if you are enhancing the TypeScript type declarations
+yarn tsd     # in addition to test:ts, also check that the type declarations work as intended
+yarn lint
 ```
 
 Also, please let us know if you encounter any issue by filing an [issue](https://github.com/patw0929/react-intl-tel-input/issues).

package.json

@@ -30,13 +30,17 @@
     "url": "https://github.com/patw0929/react-intl-tel-input/issues"
   },
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "peerDependencies": {
     "react": ">15.4.2 <17.0.0",
     "react-dom": ">15.4.2 <17.0.0"
   },
   "files": [
     "dist/**/*"
   ],
+  "tsd": {
+    "directory": "src/components/__tests__"
+  },
   "dependencies": {
     "classnames": "^2.2.5",
     "libphonenumber-js-utils": "^8.10.5",
@@ -54,6 +58,12 @@
     "@babel/preset-react": "^7.0.0",
     "@commitlint/cli": "^8.3.5",
     "@commitlint/config-conventional": "^8.3.4",
+    "@types/jquery": "^3.5.6",
+    "@types/node": "^14.0.13",
+    "@types/react": "^16.9.56",
+    "@types/react-dom": "^16.9.9",
+    "@typescript-eslint/eslint-plugin": "^4.29.0",
+    "@typescript-eslint/parser": "^4.29.0",
     "babel-core": "^7.0.0-bridge.0",
     "babel-eslint": "^10.0.1",
     "babel-jest": "^23.6.0",
@@ -67,7 +77,9 @@
     "eslint-config-airbnb": "~17.1.0",
     "eslint-config-airbnb-base": "~13.1.0",
     "eslint-config-prettier": "^6.10.0",
-    "eslint-plugin-import": "^2.14.0",
+    "eslint-import-resolver-typescript": "^2.4.0",
+    "eslint-loader": "^2.1.1",
+    "eslint-plugin-import": "^2.23.4",
     "eslint-plugin-jsx-a11y": "^6.1.1",
     "eslint-plugin-prettier": "^3.1.2",
     "eslint-plugin-react": "^7.11.0",
@@ -86,20 +98,29 @@
     "rimraf": "2.5.4",
     "sass": "^1.37.4",
     "semantic-release": "^17.0.4",
-    "sinon": "^1.17.4"
+    "sinon": "^1.17.4",
+    "tsd": "^0.17.0",
+    "typescript": "^4.3.5"
   },
   "scripts": {
     "prebuild": "yarn run clean",
-    "build": "BABEL_ENV=production babel src -d dist && cp -r ./src/*.png ./dist && sass ./src/intlTelInput.scss ./dist/main.css",
+    "build": "yarn compile:js && yarn compile:dts && yarn compile:css && yarn compile:png",
+    "compile:js": "BABEL_ENV=production babel src -d dist",
+    "compile:dts": "rsync -avh --include='*/' --include='*.d.ts' --exclude='*' src/ dist --prune-empty-dirs",
+    "compile:css": "sass ./src/intlTelInput.scss ./dist/main.css",
+    "compile:png": "cp -r -v ./src/*.png ./dist",
     "clean": "rimraf dist",
     "website:start": "yarn workspace website run start",
     "website:dryrun": "yarn workspace website run deploy:dryrun",
     "website:deploy": "yarn workspace website run deploy",
-    "lint": "eslint src website/.storybook *.js",
+    "lint": "eslint src website/.storybook --ext .js,.d.ts",
     "coverage": "yarn test --coverage",
     "coverage-upload": "NODE_ENV=development cat coverage/lcov.info | yarn coveralls",
     "test": "jest src",
     "test:watch": "jest src --watchAll --coverage",
+    "test:ts": "tsc --project ./tsconfig.test.json",
+    "test:ts-watch": "tsc --watch --project ./tsconfig.test.json",
+    "tsd": "tsd",
     "footprint": "yarn build && yarn packwatch",
     "lint:commits": "yarn commitlint --from HEAD --to HEAD --verbose"
   },

src/components/AllCountries.d.ts

@@ -0,0 +1,18 @@
+import { CountryData } from '../types'
+
+type ExternalCountry = [
+  CountryData['name'],
+  CountryData['iso2'],
+  CountryData['dialCode'],
+  CountryData['priority'],
+  CountryData['areaCodes'],
+]
+
+interface AllCountriesStatic {
+  initialize(externalCountriesList: ExternalCountry[]): void
+  getCountries(): CountryData[]
+}
+
+declare const AllCountries: AllCountriesStatic
+
+export default AllCountries

src/components/CountryList.d.ts

@@ -0,0 +1,37 @@
+import React from 'react'
+
+import { CountryData } from '../types'
+
+export interface CountryListProps {
+  setFlag?: (iso2: string) => void
+  countries?: CountryData[]
+  inputTop?: number
+  inputOuterHeight?: number
+  preferredCountries?: CountryData
+  highlightedCountry?: number
+  changeHighlightCountry?: (
+    showDropdown: boolean,
+    selectedIndex: number,
+  ) => void
+  showDropdown?: boolean
+  isMobile?: boolean
+  dropdownContainer?: string
+}
+
+export interface CountryListState {}
+
+export default class CountryList extends React.Component<
+  CountryListProps,
+  CountryListState
+> {
+  listElement?: HTMLUListElement | null
+
+  setDropdownPosition(): void
+
+  appendListItem(
+    countries: CountryData[],
+    isPreferred?: boolean,
+  ): React.ReactNode
+
+  handleMouseOver: (event: React.MouseEvent<HTMLLIElement, MouseEvent>) => void
+}

src/components/FlagBox.d.ts

@@ -0,0 +1,17 @@
+import React from 'react'
+
+export interface FlagBoxProps {
+  dialCode: string
+  isoCode: string
+  name: string
+  onMouseOver?: (event: React.MouseEvent<HTMLLIElement, MouseEvent>) => void
+  onFocus?: (event: React.FocusEvent<HTMLLIElement>) => void
+  onClick?: (event: React.MouseEvent<HTMLLIElement, MouseEvent>) => void
+  flagRef?: (instance: HTMLDivElement | null) => void
+  innerFlagRef?: (instance: HTMLDivElement | null) => void
+  countryClass: string
+}
+
+declare const FlagBox: React.FunctionComponent<FlagBoxProps>
+
+export default FlagBox

src/components/FlagDropDown.d.ts

@@ -0,0 +1,50 @@
+import React from 'react'
+
+import { CountryData } from '../types'
+
+import CountryList from './CountryList'
+
+export interface FlagDropDownProps {
+  allowDropdown?: boolean
+  dropdownContainer?: React.ElementType | string
+  separateDialCode?: boolean
+  dialCode?: string
+  countryCode?: string
+  showDropdown?: boolean
+  clickSelectedFlag?: (
+    event: React.MouseEvent<HTMLDivElement, MouseEvent>,
+  ) => void
+  handleSelectedFlagKeydown?: (
+    event: React.KeyboardEvent<HTMLDivElement>,
+  ) => void
+  isMobile?: boolean
+  setFlag?: (iso2: string) => void
+  countries?: CountryData[]
+  inputTop?: number
+  inputOuterHeight?: number
+  preferredCountries?: CountryData[]
+  highlightedCountry?: number
+  changeHighlightCountry?: (
+    showDropdown: boolean,
+    selectedIndex: number,
+  ) => void
+  titleTip?: string
+  refCallback: (instance: HTMLDivElement | null) => void
+}
+
+export interface FlagDropDownState {}
+
+export default class FlagDropDown extends React.Component<
+  FlagDropDownProps,
+  FlagDropDownState
+> {
+  countryList?: CountryList | null
+
+  genSelectedDialCode: () => React.ReactNode
+
+  genArrow: () => React.ReactNode
+
+  genFlagClassName: () => string
+
+  genCountryList: () => React.ReactNode
+}