types: add typescript typings for @mdx-js/mdx, @mdx-js/react, @mdx-js…

…/runtime, and @mdx-js/vue (#1079)

package.json

@@ -30,7 +30,9 @@
     "publish": "lerna publish --force-publish=\"*\"",
     "publish-ci": "lerna publish -y --canary --preid ci --pre-dist-tag ci",
     "publish-next": "lerna publish --force-publish=\"*\" --dist-tag next --preid rc",
-    "test": "jest --runInBand --detectOpenHandles && nyc --reporter lcov tape packages/remark-mdx/test/index.js"
+    "test": "yarn test-jest && yarn test-types",
+    "test-jest": "jest --runInBand --detectOpenHandles && nyc --reporter lcov tape packages/remark-mdx/test/index.js",
+    "test-types": "lerna run test-types"
   },
   "devDependencies": {
     "@babel/core": "7.9.6",
@@ -50,6 +52,7 @@
     "babel-plugin-macros": "2.8.0",
     "babel-plugin-remove-export-keywords": "^1.6.2",
     "babel-plugin-transform-vue-jsx": "4.0.1",
+    "dtslint": "3.6.3",
     "eslint": "7.0.0",
     "eslint-config-prettier": "6.11.0",
     "eslint-config-xo": "0.29.1",
@@ -118,7 +121,7 @@
     "*.{js,jsx,md,mdx}": [
       "eslint --cache --fix -f friendly"
     ],
-    "*.{css,html,json,yml}": [
+    "*.{css,html,json,ts,tsx,yml}": [
       "prettier --write"
     ]
   },

packages/loader/package.json

@@ -15,11 +15,14 @@
     "Tim Neutkens <[email protected]>",
     "Matija Marohnić <[email protected]>",
     "Titus Wormer <[email protected]> (https://wooorm.com)",
-    "JounQin <[email protected]> (https://www.1stg.me)"
+    "JounQin <[email protected]> (https://www.1stg.me)",
+    "Christian Murphy <[email protected]>"
   ],
   "license": "MIT",
+  "types": "types/index.d.ts",
   "files": [
-    "index.js"
+    "index.js",
+    "types/index.d.ts"
   ],
   "keywords": [
     "mdx",
@@ -31,6 +34,9 @@
     "webpack",
     "loader"
   ],
+  "scripts": {
+    "test-types": "dtslint types"
+  },
   "dependencies": {
     "@mdx-js/mdx": "^2.0.0-next.0",
     "@mdx-js/react": "^2.0.0-next.0",

packages/loader/types/index.d.ts

@@ -0,0 +1,8 @@
+// TypeScript Version: 3.4
+
+import {ComponentType} from 'react'
+
+declare module '*.mdx' {
+  const MDXComponent: ComponentType
+  export default MDXComponent
+}

packages/loader/types/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "lib": ["dom", "es6"],
+    "strict": true,
+    "skipLibCheck": true,
+    "baseUrl": ".",
+    "jsx": "react",
+    "paths": {
+      "@mdx-js/react": ["index.d.ts"]
+    }
+  }
+}

packages/loader/types/tslint.json

@@ -0,0 +1,7 @@
+{
+  "extends": "dtslint/dtslint.json",
+  "rules": {
+    "whitespace": false,
+    "semicolon": false
+  }
+}

packages/mdx/package.json

@@ -15,13 +15,16 @@
     "Tim Neutkens <[email protected]>",
     "Matija Marohnić <[email protected]>",
     "Titus Wormer <[email protected]> (https://wooorm.com)",
-    "JounQin <[email protected]> (https://www.1stg.me)"
+    "JounQin <[email protected]> (https://www.1stg.me)",
+    "Christian Murphy <[email protected]>"
   ],
   "license": "MIT",
+  "types": "types/index.d.ts",
   "files": [
     "index.js",
     "mdx-ast-to-mdx-hast.js",
     "mdx-hast-to-jsx.js",
+    "types/index.d.ts",
     "util.js"
   ],
   "keywords": [
@@ -32,6 +35,9 @@
     "remark",
     "mdxast"
   ],
+  "scripts": {
+    "test-types": "dtslint types"
+  },
   "dependencies": {
     "@babel/core": "7.9.6",
     "@babel/plugin-syntax-jsx": "7.8.3",

packages/mdx/types/index.d.ts

@@ -0,0 +1,63 @@
+// TypeScript Version: 3.4
+
+import {Plugin, Compiler, Processor} from 'unified'
+
+declare namespace mdx {
+  interface Options {
+    /**
+     * support footnotes
+     *
+     * @default true
+     */
+    footnotes?: boolean
+
+    /**
+     * remark plugins to transform markdown content
+     *
+     * @default []
+     */
+    remarkPlugins?: Plugin[]
+
+    /**
+     * rehype plugins html content
+     *
+     * @default []
+     */
+    rehypePlugins?: Plugin[]
+
+    /**
+     * compilers to customize output
+     *
+     * @default []
+     */
+    compilers?: Compiler[]
+  }
+
+  /**
+   * compile mdx text to jsx text asynchronously
+   *
+   * @param mdx content as a text
+   * @param options transform and compiler options
+   * @returns jsx text
+   */
+  function sync(mdx: string, options?: Options): string
+
+  /**
+   * Generated an MDX compiler
+   *
+   * @param options transform and compiler options
+   * @returns Unified Processor for MDX
+   */
+  function createMdxAstCompiler(options?: Options): Processor
+}
+
+/**
+ * compile mdx text to jsx text asynchronously
+ *
+ * @param mdx content as a text
+ * @param options transform and compiler options
+ * @returns jsx text
+ */
+declare function mdx(mdx: string, options?: mdx.Options): Promise<string>
+
+export = mdx

packages/mdx/types/mdx-test.ts

@@ -0,0 +1,22 @@
+import * as mdx from '@mdx-js/mdx'
+
+mdx('# title') // $ExpectType Promise<string>
+mdx('# title', {}) // $ExpectType Promise<string>
+mdx('# title', {footnotes: false}) // $ExpectType Promise<string>
+mdx('# title', {rehypePlugins: [() => () => ({type: 'test'})]}) // $ExpectType Promise<string>
+mdx('# title', {remarkPlugins: [() => () => ({type: 'test'})]}) // $ExpectType Promise<string>
+mdx('# title', {compilers: []}) // $ExpectType Promise<string>
+
+mdx.sync('# title') // $ExpectType string
+mdx.sync('# title', {}) // $ExpectType string
+mdx.sync('# title', {footnotes: false}) // $ExpectType string
+mdx.sync('# title', {rehypePlugins: [() => () => ({type: 'test'})]}) // $ExpectType string
+mdx.sync('# title', {remarkPlugins: [() => () => ({type: 'test'})]}) // $ExpectType string
+mdx.sync('# title', {compilers: []}) // $ExpectType string
+
+mdx.createMdxAstCompiler() // $ExpectType Processor<Settings>
+mdx.createMdxAstCompiler({}) // $ExpectType Processor<Settings>
+mdx.createMdxAstCompiler({footnotes: false}) // $ExpectType Processor<Settings>
+mdx.createMdxAstCompiler({rehypePlugins: [() => () => ({type: 'test'})]}) // $ExpectType Processor<Settings>
+mdx.createMdxAstCompiler({remarkPlugins: [() => () => ({type: 'test'})]}) // $ExpectType Processor<Settings>
+mdx.createMdxAstCompiler({compilers: []}) // $ExpectType Processor<Settings>

packages/mdx/types/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "lib": ["dom", "es6"],
+    "strict": true,
+    "skipLibCheck": true,
+    "baseUrl": ".",
+    "jsx": "react",
+    "paths": {
+      "@mdx-js/mdx": ["index.d.ts"]
+    }
+  }
+}

packages/mdx/types/tslint.json

@@ -0,0 +1,8 @@
+{
+  "extends": "dtslint/dtslint.json",
+  "rules": {
+    "whitespace": false,
+    "semicolon": false,
+    "no-redundant-jsdoc": false
+  }
+}

packages/react/package.json

@@ -15,13 +15,16 @@
     "Tim Neutkens <[email protected]>",
     "Matija Marohnić <[email protected]>",
     "Titus Wormer <[email protected]> (https://wooorm.com)",
-    "JounQin <[email protected]> (https://www.1stg.me)"
+    "JounQin <[email protected]> (https://www.1stg.me)",
+    "Christian Murphy <[email protected]>"
   ],
   "license": "MIT",
   "main": "dist/cjs.js",
   "module": "dist/esm.js",
+  "types": "types/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "types/index.d.ts"
   ],
   "keywords": [
     "mdx",
@@ -31,6 +34,9 @@
     "remark",
     "mdxast"
   ],
+  "scripts": {
+    "test-types": "dtslint types"
+  },
   "peerDependencies": {
     "react": "^16.9.0"
   }

packages/react/types/index.d.ts

@@ -0,0 +1,71 @@
+// TypeScript Version: 3.4
+
+import {
+  Context,
+  Consumer,
+  ComponentType,
+  FunctionComponent,
+  ReactElement,
+  createElement
+} from 'react'
+
+/**
+ * Mapping of names for JSX components to React components
+ */
+interface ComponentDictionary {
+  [name: string]: ComponentType<any>
+}
+
+/**
+ * Prop type that includes a component dictionary
+ */
+interface ComponentsProp {
+  /**
+   * Mapping of names for JSX components to React components
+   */
+  components: ComponentDictionary
+}
+
+/**
+ * Direct access to the MDX React Context
+ */
+declare const MDXContext: Context<ComponentsProp>
+
+/**
+ * Provider for MDX context
+ */
+declare const MDXProvider: FunctionComponent<ComponentsProp>
+
+/**
+ * Gets components from the MDX Context
+ *
+ * @param components additional components to include
+ * @returns all components from context with overrides from components parameter
+ */
+declare function useMDXComponents(
+  components: ComponentDictionary | (() => ComponentDictionary)
+): ComponentDictionary
+
+/**
+ * High order component that passes components prop to child
+ *
+ * @param child Component being wrapped
+ */
+declare function withMDXComponents(
+  child: ComponentType<ComponentsProp>
+): ReactElement | null
+
+/**
+ * React createElement function wrapped with handler for MDX content
+ */
+declare const mdx: typeof createElement
+
+export {
+  ComponentDictionary,
+  ComponentsProp,
+  MDXContext,
+  MDXProvider,
+  useMDXComponents,
+  withMDXComponents,
+  mdx
+}

packages/react/types/mdx-react-test.tsx

@@ -0,0 +1,35 @@
+import * as React from 'react'
+import {
+  MDXProvider,
+  useMDXComponents,
+  withMDXComponents,
+  ComponentsProp,
+  MDXContext,
+  mdx
+} from '@mdx-js/react'
+
+const H1 = ({children}: {children: React.ComponentType}) => <h1>{children}</h1>
+
+const MDXProvideExample = () => (
+  <MDXProvider components={{h1: H1}}>
+    <h1>Hello, world!</h1>
+  </MDXProvider>
+)
+
+const WithMDXComponentsExample = () =>
+  withMDXComponents(({components}: ComponentsProp) => {
+    components // $ExpectType ComponentDictionary
+    return <div />
+  })
+
+const UseMDXComponentsExample = () => {
+  useMDXComponents({h1: H1}) // $ExpectType ComponentDictionary
+  useMDXComponents(() => ({h1: H1})) // $ExpectType ComponentDictionary
+}
+
+const UseMDXContextExample = () => {
+  const {components} = React.useContext(MDXContext)
+  components // $ExpectType ComponentDictionary
+}
+
+const MDXCreateElementExample = () => mdx('mdx', {title: 'example'}, [])

packages/react/types/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "lib": ["dom", "es6"],
+    "strict": true,
+    "skipLibCheck": true,
+    "baseUrl": ".",
+    "jsx": "react",
+    "paths": {
+      "@mdx-js/react": ["index.d.ts"]
+    }
+  }
+}

packages/react/types/tslint.json

@@ -0,0 +1,7 @@
+{
+  "extends": "dtslint/dtslint.json",
+  "rules": {
+    "whitespace": false,
+    "semicolon": false
+  }
+}