Add automatic, classic runtime types

Closes GH-9

Reviewed-by: Christian Murphy <christian.murphy.42@gmail.com>

Co-authored-by: Remco Haszing <remcohaszing@gmail.com>

Author: wooorm

.gitignore

@@ -1,7 +1,12 @@
 .DS_Store
-*.d.ts
 *.log
 coverage/
 node_modules/
 test/jsx-*.js
 yarn.lock
+/*.d.ts
+test/*.d.ts
+script/*.d.ts
+lib/*.d.ts
+!lib/jsx-automatic.d.ts
+!lib/jsx-classic.d.ts

index.js

@@ -1 +1,6 @@
+/**
+ * @typedef {import('./lib/index.js').XChild}} Child Acceptable child value
+ * @typedef {import('./lib/index.js').XAttributes}} Attributes Acceptable attributes value.
+ */
+
 export {x} from './lib/index.js'

jsx-runtime.js

@@ -0,0 +1,5 @@
+/**
+ * @typedef {import('./lib/runtime.js').JSXProps}} JSXProps
+ */
+
+export * from './lib/runtime.js'

lib/index.js

@@ -10,6 +10,10 @@
  * @typedef {string|number|null|undefined} XPrimitiveChild
  * @typedef {Array.<Node|XPrimitiveChild>} XArrayChild
  * @typedef {Node|XPrimitiveChild|XArrayChild} XChild
+ * @typedef {import('./jsx-classic').Element} x.JSX.Element
+ * @typedef {import('./jsx-classic').IntrinsicAttributes} x.JSX.IntrinsicAttributes
+ * @typedef {import('./jsx-classic').IntrinsicElements} x.JSX.IntrinsicElements
+ * @typedef {import('./jsx-classic').ElementChildrenAttribute} x.JSX.ElementChildrenAttribute
  */
 
 /**

lib/jsx-automatic.d.ts

@@ -0,0 +1,42 @@
+import {XAttributes, XChild, XResult} from './index.js'
+
+export namespace JSX {
+  /**
+   * This defines the return value of JSX syntax.
+   */
+  type Element = XResult
+
+  /**
+   * This disallows the use of functional components.
+   */
+  type IntrinsicAttributes = never
+
+  /**
+   * This defines the prop types for known elements.
+   *
+   * For `xastscript` this defines any string may be used in combination with `xast` `Attributes`.
+   *
+   * This **must** be an interface.
+   */
+  // eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style
+  interface IntrinsicElements {
+    [name: string]:
+      | XAttributes
+      | {
+          /**
+           * The prop that matches `ElementChildrenAttribute` key defines the type of JSX children, defines the children type.
+           */
+          children?: XChild
+        }
+  }
+
+  /**
+   * The key of this interface defines as what prop children are passed.
+   */
+  interface ElementChildrenAttribute {
+    /**
+     * Only the key matters, not the value.
+     */
+    children?: never
+  }
+}

lib/jsx-automatic.js

@@ -0,0 +1,2 @@
+// Empty (only used for TypeScript).
+export {}

lib/jsx-classic.d.ts

@@ -0,0 +1,46 @@
+import {XAttributes, XChild, XResult} from './index.js'
+
+/**
+ * This unique symbol is declared to specify the key on which JSX children are passed, without conflicting
+ * with the Attributes type.
+ */
+declare const children: unique symbol
+
+/**
+ * This defines the return value of JSX syntax.
+ */
+export type Element = XResult
+
+/**
+ * This disallows the use of functional components.
+ */
+export type IntrinsicAttributes = never
+
+/**
+ * This defines the prop types for known elements.
+ *
+ * For `xastscript` this defines any string may be used in combination with `xast` `Attributes`.
+ *
+ * This **must** be an interface.
+ */
+// eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style
+export interface IntrinsicElements {
+  [name: string]:
+    | XAttributes
+    | {
+        /**
+         * The prop that matches `ElementChildrenAttribute` key defines the type of JSX children, defines the children type.
+         */
+        [children]?: XChild
+      }
+}
+
+/**
+ * The key of this interface defines as what prop children are passed.
+ */
+export interface ElementChildrenAttribute {
+  /**
+   * Only the key matters, not the value.
+   */
+  [children]?: never
+}

lib/jsx-classic.js

@@ -0,0 +1,2 @@
+// Empty (only used for TypeScript).
+export {}

lib/runtime.js

@@ -0,0 +1,45 @@
+/**
+ * @typedef {import('./index.js').Element} Element
+ * @typedef {import('./index.js').Root} Root
+ * @typedef {import('./index.js').XResult} XResult
+ * @typedef {import('./index.js').XChild} XChild
+ * @typedef {import('./index.js').XAttributes} XAttributes
+ * @typedef {import('./index.js').XValue} XValue
+ *
+ * @typedef {{[x: string]: XValue|XChild}} JSXProps
+ */
+
+import {x} from './index.js'
+
+// Export `JSX` as a global for TypeScript.
+export * from './jsx-automatic.js'
+
+/**
+ * Create XML trees in xast through JSX.
+ *
+ * @param name Qualified name. Case sensitive and can contain a namespace prefix (such as `rdf:RDF`). Pass `null|undefined` to build a root.
+ * @param props Map of attributes. Nullish (null or undefined) or NaN values are ignored, other values (strings, booleans) are cast to strings. `children` can contain one child or a list of children. When strings are encountered, they are mapped to text nodes.
+ */
+export const jsx =
+  /**
+   * @type {{
+   *   (name: null|undefined, props: {children?: XChild}, key?: string): Root
+   *   (name: string, props: JSXProps, key?: string): Element
+   * }}
+   */
+  (
+    /**
+     * @param {string|null} name
+     * @param {XAttributes & {children?: XChild}} props
+     * @returns {XResult}
+     */
+    function (name, props) {
+      var {children, ...properties} = props
+      return name === null ? x(name, children) : x(name, properties, children)
+    }
+  )
+
+export const jsxs = jsx
+
+/** @type {null} */
+export const Fragment = null

package.json

@@ -34,14 +34,18 @@
     "index.d.ts",
     "index.js"
   ],
+  "exports": {
+    ".": "./index.js",
+    "./index.js": "./index.js",
+    "./jsx-runtime": "./jsx-runtime.js"
+  },
   "dependencies": {
     "@types/xast": "^1.0.0"
   },
   "devDependencies": {
     "@babel/core": "^7.0.0",
     "@babel/plugin-syntax-jsx": "^7.0.0",
     "@babel/plugin-transform-react-jsx": "^7.0.0",
-    "@types/acorn": "^4.0.0",
     "@types/babel__core": "^7.0.0",
     "@types/tape": "^4.0.0",
     "astring": "^1.0.0",
@@ -61,7 +65,7 @@
   },
   "scripts": {
     "prepack": "npm run build && npm run format",
-    "build": "rimraf \"{script/**,test/**,lib/**,}*.d.ts\" && tsc && tsd && type-coverage",
+    "build": "rimraf \"{script/**,test/**,}*.d.ts\" \"lib/{index,runtime}.d.ts\" && tsc && tsd && type-coverage",
     "generate": "node script/generate-jsx",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
     "test-api": "node test/index.js",
@@ -81,10 +85,7 @@
     "rules": {
       "no-var": "off",
       "prefer-arrow-callback": "off"
-    },
-    "ignore": [
-      "types/"
-    ]
+    }
   },
   "remarkConfig": {
     "plugins": [

script/generate-jsx.js

@@ -9,7 +9,7 @@ import {buildJsx} from 'estree-util-build-jsx'
 var doc = String(fs.readFileSync(path.join('test', 'jsx.jsx')))
 
 fs.writeFileSync(
-  path.join('test', 'jsx-build-jsx.js'),
+  path.join('test', 'jsx-build-jsx-classic.js'),
   generate(
     buildJsx(
       // @ts-ignore Acorn nodes are assignable to ESTree nodes.
@@ -24,11 +24,41 @@ fs.writeFileSync(
 )
 
 fs.writeFileSync(
-  path.join('test', 'jsx-babel.js'),
+  path.join('test', 'jsx-build-jsx-automatic.js'),
+  generate(
+    buildJsx(
+      // @ts-ignore Acorn nodes are assignable to ESTree nodes.
+      Parser.extend(acornJsx()).parse(
+        doc.replace(/'name'/, "'jsx (estree-util-build-jsx, automatic)'"),
+        // @ts-ignore Hush, `2021` is fine.
+        {sourceType: 'module', ecmaVersion: 2021}
+      ),
+      {runtime: 'automatic', importSource: '.'}
+    )
+  ).replace(/\/jsx-runtime(?=["'])/g, './lib/runtime.js')
+)
+
+fs.writeFileSync(
+  path.join('test', 'jsx-babel-classic.js'),
   // @ts-ignore Result always given.
   babel.transform(doc.replace(/'name'/, "'jsx (babel, classic)'"), {
     plugins: [
       ['@babel/plugin-transform-react-jsx', {pragma: 'x', pragmaFrag: 'null'}]
     ]
   }).code
 )
+
+fs.writeFileSync(
+  path.join('test', 'jsx-babel-automatic.js'),
+  // @ts-ignore Result always given.
+  babel
+    .transformSync(doc.replace(/'name'/, "'jsx (babel, automatic)'"), {
+      plugins: [
+        [
+          '@babel/plugin-transform-react-jsx',
+          {runtime: 'automatic', importSource: '.'}
+        ]
+      ]
+    })
+    .code.replace(/\/jsx-runtime(?=["'])/g, './lib/runtime.js')
+)

test-d/automatic.tsx

@@ -0,0 +1,57 @@
+/* @jsxRuntime automatic */
+/* @jsxImportSource .. */
+
+import {expectType, expectError} from 'tsd'
+import {Root, Element} from 'xast'
+import {x} from '../index.js'
+import {Fragment, jsx, jsxs} from '../jsx-runtime.js'
+
+type Result = Element | Root
+
+// JSX automatic runtime.
+expectType<Root>(jsx(Fragment, {}))
+expectType<Root>(jsx(Fragment, {children: x('x')}))
+expectType<Element>(jsx('a', {}))
+expectType<Element>(jsx('a', {children: 'a'}))
+expectType<Element>(jsx('a', {children: x('x')}))
+expectType<Element>(jsxs('a', {children: ['a', 'b']}))
+expectType<Element>(jsxs('a', {children: [x('x'), x('y')]}))
+
+expectType<Result>(<></>)
+expectType<Result>(<a />)
+expectType<Result>(<a b="c" />)
+expectType<Result>(<a b={'c'} />)
+expectType<Result>(<a>string</a>)
+expectType<Result>(<a>{['string', 'string']}</a>)
+expectType<Result>(
+  <a>
+    <></>
+  </a>
+)
+expectType<Result>(<a>{x()}</a>)
+expectType<Result>(<a>{x('b')}</a>)
+expectType<Result>(
+  <a>
+    <b />c
+  </a>
+)
+expectType<Result>(
+  <a>
+    <b />
+    <c />
+  </a>
+)
+expectType<Result>(<a>{[<b />, <c />]}</a>)
+expectType<Result>(<a>{[<b />, <c />]}</a>)
+expectType<Result>(<a>{[]}</a>)
+
+expectError(<a invalid={{}} />)
+expectError(<a invalid={[1]} />)
+expectError(<a>{{invalid: 'child'}}</a>)
+
+// This is where the automatic runtime differs from the classic runtime.
+// The automatic runtime the children prop to define JSX children, whereas it’s used as an attribute in the classic runtime.
+expectType<Result>(<a children={<b />} />)
+
+declare function Bar(props?: Record<string, unknown>): Element
+expectError(<Bar />)

test-d/classic.tsx

@@ -0,0 +1,47 @@
+/* @jsx x */
+/* @jsxFrag null */
+import {expectType, expectError} from 'tsd'
+import {Root, Element} from 'xast'
+import {x} from '../index.js'
+
+type Result = Element | Root
+
+expectType<Result>(<></>)
+expectType<Result>(<a />)
+expectType<Result>(<a b="c" />)
+expectType<Result>(<a b={'c'} />)
+expectType<Result>(<a>string</a>)
+expectType<Result>(<a>{['string', 'string']}</a>)
+expectType<Result>(
+  <a>
+    <></>
+  </a>
+)
+expectType<Result>(<a>{x()}</a>)
+expectType<Result>(<a>{x('b')}</a>)
+expectType<Result>(
+  <a>
+    <b />c
+  </a>
+)
+expectType<Result>(
+  <a>
+    <b />
+    <c />
+  </a>
+)
+expectType<Result>(<a>{[<b />, <c />]}</a>)
+expectType<Result>(<a>{[<b />, <c />]}</a>)
+expectType<Result>(<a>{[]}</a>)
+
+expectError(<a invalid={{}} />)
+expectError(<a invalid={[1]} />)
+expectError(<a>{{invalid: 'child'}}</a>)
+
+// This is where the classic runtime differs from the automatic runtime.
+// The automatic runtime the children prop to define JSX children, whereas it’s
+// used as an attribute in the classic runtime.
+expectError(<a children={<b />} />)
+
+declare function Bar(props?: Record<string, unknown>): Element
+expectError(<Bar />)

index.test-d.ts renamed to test-d/index.tsx

@@ -1,6 +1,6 @@
 import {expectType, expectError} from 'tsd'
 import {Root, Element} from 'xast'
-import {x} from './index.js'
+import {x} from '../index.js'
 
 expectType<Root>(x())
 expectError(x(true))

test/index.js

@@ -1,5 +1,7 @@
 /* eslint-disable import/no-unassigned-import */
 import './core.js'
-import './jsx-babel.js'
-import './jsx-build-jsx.js'
+import './jsx-babel-classic.js'
+import './jsx-babel-automatic.js'
+import './jsx-build-jsx-classic.js'
+import './jsx-build-jsx-automatic.js'
 /* eslint-enable import/no-unassigned-import */