Refactor code-style

* Refactor a bunch of code
* Add more JSDoc

Author: wooorm

index.js

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

jsx-dev-runtime.js

@@ -1,20 +1,23 @@
 /**
  * @typedef {import('xast').Element} Element
  * @typedef {import('xast').Root} Root
- * @typedef {import('./lib/index.js').XChild} XChild
+ * @typedef {import('./lib/index.js').Child} Child
  * @typedef {import('./lib/runtime.js').JSXProps} JSXProps
  */
 
-import {jsx} from './jsx-runtime.js'
+import {jsx} from './lib/runtime.js'
+
+// Export `JSX` as a global for TypeScript.
+export * from './lib/jsx-automatic.js'
 
 export {Fragment} from './jsx-runtime.js'
 
 // eslint-disable-next-line unicorn/prefer-export-from
 export const jsxDEV =
   /**
    * @type {{
-   *   (name: null | undefined, props: {children?: XChild}, ...unused: unknown[]): Root
-   *   (name: string, props: JSXProps, ...unused: unknown[]): Element
+   *   (name: null | undefined, props: {children?: Child}, key?: string, ...unused: Array<unknown>): Root
+   *   (name: string, props: JSXProps, key?: string, ...unused: Array<unknown>): Element
    * }}
    */
   (jsx)

jsx-runtime.js

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

lib/index.js

@@ -4,15 +4,25 @@
  */
 
 /**
- * @typedef {Root['children'][number]} Child
- * @typedef {Child | Root} Node
- * @typedef {Root | Element} XResult
- * @typedef {string | number | boolean | null | undefined} XValue
- * @typedef {{[attribute: string]: XValue}} XAttributes Attributes to support JS primitive types
+ * @typedef {Root['children'][number]} Content
+ * @typedef {Content | Root} Node
+ *   Any concrete `xast` node.
+ *
+ * @typedef {Root | Element} Result
+ *   Result from a `x` call.
+ *
+ * @typedef {string | number | boolean | null | undefined} Value
+ *   Attribute value
+ * @typedef {{[attribute: string]: Value}} Attributes
+ *   Acceptable value for element properties.
+ *
+ * @typedef {string | number | null | undefined} PrimitiveChild
+ *   Primitive children, either ignored (nullish), or turned into text nodes.
+ * @typedef {Array<Node | PrimitiveChild>} ArrayChild
+ *   List of children.
+ * @typedef {Node | PrimitiveChild | ArrayChild} Child
+ *   Acceptable child value.
  *
- * @typedef {string | number | null | undefined} XPrimitiveChild
- * @typedef {Array<Node | XPrimitiveChild>} XArrayChild
- * @typedef {Node | XPrimitiveChild | XArrayChild} XChild
  * @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
@@ -22,31 +32,48 @@
 /**
  * Create XML trees in xast.
  *
- * @param name Qualified name. Case sensitive and can contain a namespace prefix (such as `rdf:RDF`). Pass `null | undefined` to build a root.
- * @param attributes Map of attributes. Nullish (null or undefined) or NaN values are ignored, other values (strings, booleans) are cast to strings.
- * @param children (Lists of) child nodes. When strings are encountered, they are mapped to Text nodes.
+ * @param 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 attributes
+ *   Map of attributes.
+ *
+ *   Nullish (`null` or `undefined`) or `NaN` values are ignored, other values
+ *   are turned to strings.
+ *
+ *   Cannot be given if building a `Root`.
+ *   Cannot be omitted when building an `Element` if the first child is a
+ *   `Node`.
+ * @param children
+ *   (Lists of) children.
+ *
+ *   When strings or numbers are encountered, they are mapped to `Text` nodes.
+ *   If a `Root` node is encountered, its children are used instead.
+ * @returns
+ *   `Element` or `Root`.
  */
 export const x =
   /**
    * @type {{
    *   (): Root
-   *   (name: null | undefined, ...children: Array<XChild>): Root
-   *   (name: string, attributes: XAttributes, ...children: Array<XChild>): Element
-   *   (name: string, ...children: Array<XChild>): Element
+   *   (name: null | undefined, ...children: Array<Child>): Root
+   *   (name: string, attributes?: Attributes, ...children: Array<Child>): Element
+   *   (name: string, ...children: Array<Child>): Element
    * }}
    */
   (
     /**
-     * Hyperscript compatible DSL for creating virtual xast trees.
-     *
-     * @param {string | null} [name]
-     * @param {XAttributes | XChild} [attributes]
-     * @param {Array<XChild>} children
-     * @returns {XResult}
+     * @param {string | null | undefined} [name]
+     * @param {Attributes | Child | null | undefined} [attributes]
+     * @param {Array<Child>} children
+     * @returns {Result}
      */
     function (name, attributes, ...children) {
       let index = -1
-      /** @type {XResult} */
+      /** @type {Result} */
       let node
 
       if (name === undefined || name === null) {
@@ -89,8 +116,14 @@ export const x =
   )
 
 /**
+ * Add children.
+ *
  * @param {Array<Child>} nodes
- * @param {XChild} value
+ *   List of nodes.
+ * @param {Child} value
+ *   Child.
+ * @returns {void}
+ *   Nothing.
  */
 function addChild(nodes, value) {
   let index = -1
@@ -115,8 +148,12 @@ function addChild(nodes, value) {
 }
 
 /**
- * @param {XAttributes | XChild} value
- * @returns {value is XAttributes}
+ * Check if `value` is `Attributes`.
+ *
+ * @param {Attributes | Child} value
+ *   Value.
+ * @returns {value is Attributes}
+ *   Whether `value` is `Attributes`.
  */
 function isAttributes(value) {
   if (

lib/jsx-automatic.d.ts

@@ -1,11 +1,11 @@
 /* eslint-disable-next-line @typescript-eslint/consistent-type-imports -- fix in major */
-import {XAttributes, XChild, XResult} from './index.js'
+import {Attributes, Child, Result} from './index.js'
 
 export namespace JSX {
   /**
    * This defines the return value of JSX syntax.
    */
-  type Element = XResult
+  type Element = Result
 
   /**
    * This disallows the use of functional components.
@@ -24,12 +24,12 @@ export namespace JSX {
   // eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style
   interface IntrinsicElements {
     [name: string]:
-      | XAttributes
+      | Attributes
       | {
           /**
            * The prop that matches `ElementChildrenAttribute` key defines the type of JSX children, defines the children type.
            */
-          children?: XChild
+          children?: Child
         }
   }
 

lib/jsx-classic.d.ts

@@ -1,5 +1,5 @@
 /* eslint-disable-next-line @typescript-eslint/consistent-type-imports -- fix in major */
-import {XAttributes, XChild, XResult} from './index.js'
+import {Attributes, Child, Result} from './index.js'
 
 /**
  * This unique symbol is declared to specify the key on which JSX children are passed, without conflicting
@@ -10,7 +10,7 @@ declare const children: unique symbol
 /**
  * This defines the return value of JSX syntax.
  */
-export type Element = XResult
+export type Element = Result
 
 /**
  * This disallows the use of functional components.
@@ -29,12 +29,12 @@ export type IntrinsicAttributes = never
 // eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style
 export interface IntrinsicElements {
   [name: string]:
-    | XAttributes
+    | Attributes
     | {
         /**
          * The prop that matches `ElementChildrenAttribute` key defines the type of JSX children, defines the children type.
          */
-        [children]?: XChild
+        [children]?: Child
       }
 }
 

lib/runtime.js

@@ -1,37 +1,47 @@
 /**
  * @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 {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]: XValue | XChild}} JSXProps
+ * @typedef {{[x: string]: Value | Child}} 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.
+ * @param 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
+ *   Map of attributes.
+ *
+ *   Nullish (`null` or `undefined`) or `NaN` values are ignored, other values
+ *   are turned to strings.
+ *
+ *   Cannot be given if building a `Root`.
+ *   Cannot be omitted when building an `Element` if the first child is a
+ *   `Node`.
  */
 export const jsx =
   /**
    * @type {{
-   *   (name: null | undefined, props: {children?: XChild}, key?: string): Root
+   *   (name: null | undefined, props: {children?: Child}, key?: string): Root
    *   (name: string, props: JSXProps, key?: string): Element
    * }}
    */
   (
     /**
      * @param {string | null} name
-     * @param {XAttributes & {children?: XChild}} props
-     * @returns {XResult}
+     * @param {Attributes & {children?: Child}} props
+     * @returns {Result}
      */
     function (name, props) {
       const {children, ...properties} = props
@@ -41,5 +51,4 @@ export const jsx =
 
 export const jsxs = jsx
 
-/** @type {null} */
 export const Fragment = null

readme.md

@@ -209,6 +209,7 @@ Create [xast][] trees.
 ###### `name`
 
 Qualified name (`string`, optional).
+
 Case sensitive and can contain a namespace prefix (such as `rdf:RDF`).
 When string, an [`Element`][element] is built.
 When nullish, a [`Root`][root] is built instead.