Refactor code-style

Author: wooorm

index.js

@@ -1,6 +1,6 @@
 /**
- * @typedef {import('./lib/index.js').Child} Child
  * @typedef {import('./lib/index.js').Attributes} Attributes
+ * @typedef {import('./lib/index.js').Child} Child
  * @typedef {import('./lib/index.js').Result} Result
  */
 

jsx-runtime.js

@@ -1,8 +1,8 @@
 /**
- * @typedef {import('./lib/runtime.js').JSXProps}} JSXProps
+ * @typedef {import('./lib/runtime.js').JSXProps} JSXProps
  */
 
 // Export `JSX` as a global for TypeScript.
 export * from './lib/jsx-automatic.js'
 
-export {jsx, jsxs, Fragment} from './lib/runtime.js'
+export {Fragment, jsx, jsxs} from './lib/runtime.js'

lib/index.js

@@ -1,28 +1,30 @@
 /**
- * @typedef {import('xast').Root} Root
  * @typedef {import('xast').Element} Element
+ * @typedef {import('xast').Nodes} Nodes
+ * @typedef {import('xast').Root} Root
  */
 
 /**
- * @typedef {Root['children'][number]} Content
- * @typedef {Content | Root} Node
- *   Any concrete `xast` node.
- *
- * @typedef {Root | Element} Result
+ * @typedef {Element | Root} Result
  *   Result from a `x` call.
  *
- * @typedef {string | number | boolean | null | undefined} Value
+ * @typedef {boolean | number | string | null | undefined} Value
  *   Attribute value
+ *
  * @typedef {{[attribute: string]: Value}} Attributes
  *   Acceptable value for element properties.
  *
- * @typedef {string | number | null | undefined} PrimitiveChild
+ * @typedef {boolean | number | string | null | undefined} PrimitiveChild
  *   Primitive children, either ignored (nullish), or turned into text nodes.
- * @typedef {Array<Node | PrimitiveChild>} ArrayChild
+ * @typedef {Array<Nodes | PrimitiveChild>} ArrayChild
  *   List of children.
- * @typedef {Node | PrimitiveChild | ArrayChild} Child
+ * @typedef {Nodes | PrimitiveChild | ArrayChild} Child
  *   Acceptable child value.
- *
+ */
+
+// Define JSX.
+
+/**
  * @typedef {import('./jsx-classic.js').Element} x.JSX.Element
  * @typedef {import('./jsx-classic.js').IntrinsicAttributes} x.JSX.IntrinsicAttributes
  * @typedef {import('./jsx-classic.js').IntrinsicElements} x.JSX.IntrinsicElements
@@ -39,13 +41,14 @@
  *   When string, an `Element` is built.
  *   When nullish, a `Root` is built instead.
  * @param attributes
- *   Attributes of the element.
+ *   Attributes of the element or first child.
  * @param children
  *   Children of the node.
  * @returns
  *   `Element` or `Root`.
  */
 export const x =
+  // Note: not yet possible to use the spread `...children` in JSDoc overloads.
   /**
    * @type {{
    *   (): Root
@@ -68,7 +71,7 @@ export const x =
 
       if (name === undefined || name === null) {
         node = {type: 'root', children: []}
-        // @ts-expect-error Root builder doesn’t accept attributes.
+        // @ts-expect-error: Root builder doesn’t accept attributes.
         children.unshift(attributes)
       } else if (typeof name === 'string') {
         node = {type: 'element', name, attributes: {}, children: []}
@@ -111,7 +114,7 @@ export const x =
  *   List of nodes.
  * @param {Child} value
  *   Child.
- * @returns {void}
+ * @returns {undefined}
  *   Nothing.
  */
 function addChild(nodes, value) {

lib/jsx-automatic.d.ts

@@ -1,5 +1,4 @@
-/* eslint-disable-next-line @typescript-eslint/consistent-type-imports -- fix in major */
-import {Attributes, Child, Result} from './index.js'
+import type {Attributes, Child, Result} from './index.js'
 
 export namespace JSX {
   /**
@@ -12,16 +11,13 @@ export namespace JSX {
    */
   type IntrinsicAttributes = never
 
-  /* eslint-disable @typescript-eslint/consistent-type-definitions -- interfaces are required here */
-
   /**
    * 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]:
       | Attributes
@@ -42,6 +38,4 @@ export namespace JSX {
      */
     children?: never
   }
-
-  /* eslint-enable @typescript-eslint/consistent-type-definitions */
 }

lib/jsx-classic.d.ts

@@ -1,5 +1,4 @@
-/* eslint-disable-next-line @typescript-eslint/consistent-type-imports -- fix in major */
-import {Attributes, Child, Result} from './index.js'
+import type {Attributes, Child, Result} from './index.js'
 
 /**
  * This unique symbol is declared to specify the key on which JSX children are passed, without conflicting
@@ -17,16 +16,13 @@ export type Element = Result
  */
 export type IntrinsicAttributes = never
 
-/* eslint-disable @typescript-eslint/consistent-type-definitions -- interfaces are required here */
-
 /**
  * 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]:
     | Attributes
@@ -47,5 +43,3 @@ export interface ElementChildrenAttribute {
    */
   [children]?: never
 }
-
-/* eslint-enable @typescript-eslint/consistent-type-definitions */

lib/runtime.js

@@ -1,26 +1,38 @@
 /**
+ * @typedef {import('./index.js').Child} Child
  * @typedef {import('./index.js').Element} Element
  * @typedef {import('./index.js').Root} Root
- * @typedef {import('./index.js').Result} Result
- * @typedef {import('./index.js').Child} Child
- * @typedef {import('./index.js').Attributes} Attributes
  * @typedef {import('./index.js').Value} Value
- *
- * @typedef {{[x: string]: Value | Child}} JSXProps
+ */
+
+/**
+ * @typedef {{[x: string]: Child | Value}} JSXProps
  */
 
 import {x} from './index.js'
 
 /**
  * Create XML trees in xast through JSX.
  *
- * @param name
+ * @overload
+ * @param {null} name
+ * @param {{children?: Child}} props
+ * @param {string} [key]
+ * @returns {Root}
+ *
+ * @overload
+ * @param {string} name
+ * @param {JSXProps} props
+ * @param {string} [key]
+ * @returns {Element}
+ *
+ * @param {string | null}  name
  *   Qualified name.
  *
  *   Case sensitive and can contain a namespace prefix (such as `rdf:RDF`).
  *   When string, an `Element` is built.
  *   When nullish, a `Root` is built instead.
- * @param props
+ * @param {JSXProps}  props
  *   Map of attributes.
  *
  *   Nullish (`null` or `undefined`) or `NaN` values are ignored, other values
@@ -29,25 +41,18 @@ import {x} from './index.js'
  *   Cannot be given if building a `Root`.
  *   Cannot be omitted when building an `Element` if the first child is a
  *   `Node`.
+ * @param {string | null | undefined}  [_key]
+ *   Key (not used).
+ * @returns {Element | Root}
+ *   Result.
  */
-export const jsx =
-  /**
-   * @type {{
-   *   (name: null | undefined, props: {children?: Child}, key?: string): Root
-   *   (name: string, props: JSXProps, key?: string): Element
-   * }}
-   */
-  (
-    /**
-     * @param {string | null} name
-     * @param {Attributes & {children?: Child}} props
-     * @returns {Result}
-     */
-    function (name, props) {
-      const {children, ...properties} = props
-      return name === null ? x(name, children) : x(name, properties, children)
-    }
-  )
+export function jsx(name, props, _key) {
+  const {children, ...properties} = props
+  return name === null
+    ? x(name, children)
+    : // @ts-expect-error: overloads are complex.
+      x(name, properties, children)
+}
 
 export const jsxs = jsx
 

package.json

@@ -63,7 +63,7 @@
     "xo": "^0.55.0"
   },
   "scripts": {
-    "prepack": "npm run build && npm run format",
+    "prepack": "npm run generate && npm run build && npm run format",
     "generate": "node script/generate-jsx.js",
     "build": "tsc --build --clean && tsc --build && tsd && type-coverage",
     "format": "remark . -qfo && prettier . -w --log-level warn && xo --fix",
@@ -91,6 +91,17 @@
     "strict": true
   },
   "xo": {
+    "overrides": [
+      {
+        "files": [
+          "**/*.ts"
+        ],
+        "rules": {
+          "@typescript-eslint/consistent-indexed-object-style": "off",
+          "@typescript-eslint/consistent-type-definitions": "off"
+        }
+      }
+    ],
     "prettier": true,
     "rules": {
       "n/file-extension-in-import": "off"

readme.md

@@ -242,7 +242,7 @@ turned to strings.
 ###### Type
 
 ```ts
-type Attributes = Record<string, string | number | boolean | null | undefined>
+type Attributes = Record<string, boolean | number | string | null | undefined>
 ```
 
 ### `Child`
@@ -258,12 +258,13 @@ are used instead.
 
 ```ts
 type Child =
-  | string
+  | Array<Node | boolean | number | string | null | undefined>
+  | Node
+  | boolean
   | number
+  | string
   | null
   | undefined
-  | Node
-  | Array<string | number | null | undefined | Node>
 ```
 
 ### `Result`
@@ -273,7 +274,7 @@ Result from a `x` call (TypeScript type).
 ###### Type
 
 ```ts
-type Result = Root | Element
+type Result = Element | Root
 ```
 
 ## Syntax tree

script/generate-jsx.js

@@ -1,8 +1,8 @@
 import fs from 'node:fs/promises'
 import acornJsx from 'acorn-jsx'
+import {buildJsx} from 'estree-util-build-jsx'
 import {fromJs} from 'esast-util-from-js'
 import {toJs} from 'estree-util-to-js'
-import {buildJsx} from 'estree-util-build-jsx'
 
 const doc = String(
   await fs.readFile(new URL('../test/jsx.jsx', import.meta.url))
@@ -36,16 +36,18 @@ await fs.writeFile(
 
 await fs.writeFile(
   new URL('../test/jsx-build-jsx-automatic-development.js', import.meta.url),
-  toJs(
-    buildJsx(
-      fromJs(
-        doc.replace(
-          /'name'/,
-          "'jsx (estree-util-build-jsx, automatic, development)'"
+  // There’s a problem with `this` that TS doesn’t like.
+  '// @ts-nocheck\n\n' +
+    toJs(
+      buildJsx(
+        fromJs(
+          doc.replace(
+            /'name'/,
+            "'jsx (estree-util-build-jsx, automatic, development)'"
+          ),
+          {plugins: [acornJsx()], module: true}
         ),
-        {plugins: [acornJsx()], module: true}
-      ),
-      {runtime: 'automatic', importSource: 'xastscript', development: true}
-    )
-  ).value
+        {runtime: 'automatic', importSource: 'xastscript', development: true}
+      )
+    ).value
 )

test-d/automatic.tsx

@@ -1,8 +1,8 @@
 /* @jsxRuntime automatic */
 /* @jsxImportSource xastscript */
 
-import {expectType, expectError} from 'tsd'
-import type {Root, Element} from 'xast'
+import {expectType} from 'tsd'
+import type {Element, Root} from 'xast'
 import {x} from '../index.js'
 import {Fragment, jsx, jsxs} from '../jsx-runtime.js'
 
@@ -41,17 +41,25 @@ expectType<Result>(
     <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>)
+// @ts-expect-error: not a valid child.
+expectType<Result>(<a invalid={{}} />)
+
+// @ts-expect-error: not a valid child.
+expectType<Result>(<a invalid={[1]} />)
+
+// @ts-expect-error: not a valid child.
+expectType<Result>(<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 />)
+
+// @ts-expect-error: components not supported.
+expectType<Result>(<Bar />)