Merge pull request #96 from nikolay-borzov/typescript-definitions

chore(typescript): add definitions

.travis.yml

@@ -5,6 +5,7 @@ install:
 - npm install
 script:
 - npm run lint
+- npm run dtslint
 - npm run cover
 - npm run build
 - npm run benchmark

package.json

@@ -4,16 +4,18 @@
   "description": "An HTML to React parser.",
   "author": "Mark <[email protected]>",
   "main": "index.js",
+  "types": "types",
   "scripts": {
     "benchmark": "node benchmark",
     "build": "npm run clean && npm run build:min && npm run build:unmin",
-    "build:min": "NODE_ENV=production webpack -o dist/html-react-parser.min.js",
-    "build:unmin": "NODE_ENV=development webpack -o dist/html-react-parser.js",
-    "clean": "rm -rf dist",
+    "build:min": "cross-env NODE_ENV=production webpack -o dist/html-react-parser.min.js",
+    "build:unmin": "cross-env NODE_ENV=development webpack -o dist/html-react-parser.js",
+    "clean": "rimraf dist",
     "cover": "istanbul cover _mocha -- -R spec \"test/**/*\"",
     "coveralls": "cat coverage/lcov.info | coveralls",
     "lint": "eslint --ignore-path .gitignore .",
     "lint:fix": "npm run lint -- --fix",
+    "dtslint": "dtslint types",
     "prepublishOnly": "npm run build",
     "release": "standard-version --no-verify",
     "test": "mocha"
@@ -40,8 +42,11 @@
   "devDependencies": {
     "@commitlint/cli": "^7.2.1",
     "@commitlint/config-conventional": "^7.1.2",
+    "@types/react": "16.8.8",
     "benchmark": "2.1.4",
     "coveralls": "^3.0.2",
+    "cross-env": "5.2.0",
+    "dtslint": "0.5.5",
     "eslint": "^5.10.0",
     "eslint-plugin-prettier": "^3.0.0",
     "husky": "^1.3.0",
@@ -51,6 +56,7 @@
     "prettier": "^1.15.3",
     "react": "^16",
     "react-dom": "^16",
+    "rimraf": "2.6.3",
     "standard-version": "^4.4.0",
     "webpack": "^4.27.1",
     "webpack-cli": "^3.1.2"
@@ -60,7 +66,8 @@
   },
   "files": [
     "dist",
-    "lib"
+    "lib",
+    "types/index.d.ts"
   ],
   "license": "MIT"
 }

types/index.d.ts

@@ -0,0 +1,40 @@
+// TypeScript Version: 3.3
+
+import * as React from 'react';
+
+export as namespace HTMLReactParser;
+
+export default HTMLReactParser;
+
+type ReactElement = React.DetailedReactHTMLElement<{}, HTMLElement>;
+
+export interface HTMLReactParserOptions {
+  // TODO: Replace `object` by type for objects like `{ type: 'h1', props: { children: 'Heading' } }`
+  replace(domNode: DomNode): React.ReactElement | object | undefined | false;
+}
+
+/**
+ * Convert HTML string to React elements.
+ * @returns ReactElement on successful parse or string when `html` cannot be
+ * parsed as HTML
+ */
+declare function HTMLReactParser(
+  html: string,
+  options?: HTMLReactParserOptions
+): ReactElement | ReactElement[] | string;
+
+/** domhandler node */
+export interface DomNode {
+  type: 'tag' | 'text' | 'directive' | 'comment' | 'script' | 'style';
+  name: string;
+  data?: string;
+  attribs?: {
+    [attributeName: string]: string;
+  };
+  children?: DomNode[];
+  parent?: DomNode;
+  prev?: DomNode;
+  next?: DomNode;
+  startIndex?: number;
+  endIndex?: number;
+}

types/test.tsx

@@ -0,0 +1,37 @@
+import parse, { HTMLReactParserOptions } from 'html-dom-parser';
+import * as React from 'react';
+
+// $ExpectType string | DetailedReactHTMLElement<{}, HTMLElement> | DetailedReactHTMLElement<{}, HTMLElement>[]
+parse('<div>text</div>');
+
+// `options.replace`
+
+// Return React.createElement from `replace`
+parse('<p id="replace">text</p>', {
+  replace: domNode => {
+    if (domNode.attribs && domNode.attribs.id === 'replace') {
+      return React.createElement('span', {}, 'replaced');
+    }
+  }
+});
+
+// Return ReactElement
+const options: HTMLReactParserOptions = {
+  replace({ attribs }) {
+    return attribs && attribs.id === 'remove' && <React.Fragment />;
+  }
+};
+
+parse('<p><br id="remove"></p>', options);
+
+// Return domhandler node
+parse('<a id="header" href="#">Heading</a>', {
+  replace: node => {
+    if (node.attribs && node.attribs.id === 'header') {
+      return {
+        type: 'h1',
+        props: { children: 'Heading' }
+      };
+    }
+  }
+});

types/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "module": "esnext",
+    "lib": ["es6"],
+    "noImplicitAny": true,
+    "noImplicitThis": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "noEmit": true,
+    "jsx": "react",
+    "baseUrl": ".",
+    "paths": { "html-dom-parser": ["."] },
+    "moduleResolution": "node"
+  }
+}