Refactor code-style

*   Add support for `null` as input in API types
*   Refactor some code
*   Add more docs to JSDoc

Author: wooorm

lib/index.js

@@ -1,33 +1,50 @@
 /**
+ * @typedef {import('property-information').Schema} Schema
+ * @typedef {import('hast').Content} Content
  * @typedef {import('hast').Element} Element
  * @typedef {import('hast').Root} Root
- * @typedef {import('hast').Text} Text
- * @typedef {import('hast').Root|import('hast').Content} Node
+ */
+
+/**
+ * @typedef {Root | Content} Node
  *
  * @callback CreateElementLike
+ *   Function that works somewhat like `React.createElement`.
  * @param {string} name
+ *   Element name.
  * @param {any} attributes
+ *   Properties.
  * @param {Array<any>} [children]
+ *   Children.
  * @returns {any}
+ *   Something.
  *
- * @typedef Context
- * @property {html|svg} schema
- * @property {string|null} prefix
+ * @typedef State
+ *   Info passed around.
+ * @property {Schema} schema
+ *   Current schema.
+ * @property {string | undefined} prefix
+ *   Prefix to use.
  * @property {number} key
+ *   Current key.
  * @property {boolean} react
+ *   Looks like React.
  * @property {boolean} vue
+ *   Looks like Vue.
  * @property {boolean} vdom
+ *   Looks like vdom.
  * @property {boolean} hyperscript
+ *   Looks like `hyperscript`.
  *
  * @typedef Options
- *   Configuration (optional).
- * @property {string|null} [prefix]
+ *   Configuration.
+ * @property {string | null | undefined} [prefix]
  *   Prefix to use as a prefix for keys passed in `props` to `h()`, this
  *   behavior is turned off by passing `false` and turned on by passing a
  *   `string`.
  *   By default, `h-` is used as a prefix if the given `h` is detected as being
  *   `virtual-dom/h` or `React.createElement`
- * @property {'html'|'svg'} [space]
+ * @property {'html' | 'svg' | null | undefined} [space]
  *   Whether `node` is in the `'html'` or `'svg'` space.
  *   If an `<svg>` element is found when inside the HTML space, `toH`
  *   automatically switches to the SVG space when entering the element, and
@@ -44,19 +61,19 @@ import {webNamespaces} from 'web-namespaces'
 /** @type {(value: string, replacer: ((key: string, value: string) => void)) => void} */
 const style = styleToObject
 
-const toReact = /** @type {Record<string, string>} */ (hastToReact)
-
 const own = {}.hasOwnProperty
 
 /**
  * @template {CreateElementLike} H
+ *   Type of hyperscript function.
  * @param {H} h
  *   HyperScript function.
  * @param {Node} tree
  *   Tree to transform.
- * @param {string|boolean|Options} [options]
+ * @param {string | boolean | Options | null | undefined} [options]
  *   Configuration (optional).
  * @returns {ReturnType<H>}
+ *   Return type of the hyperscript function.
  */
 // eslint-disable-next-line complexity
 export function toH(h, tree, options) {
@@ -106,12 +123,12 @@ export function toH(h, tree, options) {
       prefix === undefined || prefix === null
         ? r || v || vd
           ? 'h-'
-          : null
+          : undefined
         : typeof prefix === 'string'
         ? prefix
         : prefix
         ? 'h-'
-        : null,
+        : undefined,
     key: 0,
     react: r,
     vue: v,
@@ -124,12 +141,18 @@ export function toH(h, tree, options) {
  * Transform a hast node through a hyperscript interface to *anything*!
  *
  * @template {CreateElementLike} H
+ *   Type of hyperscript function.
  * @param {H} h
+ *   HyperScript function.
  * @param {Element} node
- * @param {Context} ctx
+ *   Node to transform.
+ * @param {State} state
+ *   Info passed around.
+ * @returns {ReturnType<H>}
+ *   Return type of the hyperscript function.
  */
-function transform(h, node, ctx) {
-  const parentSchema = ctx.schema
+function transform(h, node, state) {
+  const parentSchema = state.schema
   let schema = parentSchema
   let name = node.tagName
   /** @type {Record<string, unknown>} */
@@ -142,42 +165,42 @@ function transform(h, node, ctx) {
 
   if (parentSchema.space === 'html' && name.toLowerCase() === 'svg') {
     schema = svg
-    ctx.schema = schema
+    state.schema = schema
   }
 
   for (key in node.properties) {
     if (node.properties && own.call(node.properties, key)) {
-      addAttribute(attributes, key, node.properties[key], ctx, name)
+      addAttribute(attributes, key, node.properties[key], state, name)
     }
   }
 
-  if (ctx.vdom) {
+  if (state.vdom) {
     if (schema.space === 'html') {
       name = name.toUpperCase()
     } else if (schema.space) {
       attributes.namespace = webNamespaces[schema.space]
     }
   }
 
-  if (ctx.prefix) {
-    ctx.key++
-    attributes.key = ctx.prefix + ctx.key
+  if (state.prefix) {
+    state.key++
+    attributes.key = state.prefix + state.key
   }
 
   if (node.children) {
     while (++index < node.children.length) {
       const value = node.children[index]
 
       if (value.type === 'element') {
-        nodes.push(transform(h, value, ctx))
+        nodes.push(transform(h, value, state))
       } else if (value.type === 'text') {
         nodes.push(value.value)
       }
     }
   }
 
   // Restore parent schema.
-  ctx.schema = parentSchema
+  state.schema = parentSchema
 
   // Ensure no React warnings are triggered for void elements having children
   // passed in.
@@ -187,16 +210,25 @@ function transform(h, node, ctx) {
 }
 
 /**
+ * Add an attribute to `props`.
+ *
  * @param {Record<string, unknown>} props
+ *   Map.
  * @param {string} prop
+ *   Key.
  * @param {unknown} value
- * @param {Context} ctx
+ *   Value.
+ * @param {State} state
+ *   Info passed around.
  * @param {string} name
+ *   Element name.
+ * @returns {void}
+ *   Nothing.
  */
 // eslint-disable-next-line complexity, max-params
-function addAttribute(props, prop, value, ctx, name) {
-  const info = find(ctx.schema, prop)
-  /** @type {string|undefined} */
+function addAttribute(props, prop, value, state, name) {
+  const info = find(state.schema, prop)
+  /** @type {string | undefined} */
   let subprop
 
   // Ignore nullish and `NaN` values.
@@ -205,8 +237,8 @@ function addAttribute(props, prop, value, ctx, name) {
     value === undefined ||
     value === null ||
     (typeof value === 'number' && Number.isNaN(value)) ||
-    (value === false && (ctx.vue || ctx.vdom || ctx.hyperscript)) ||
-    (!value && info.boolean && (ctx.vue || ctx.vdom || ctx.hyperscript))
+    (value === false && (state.vue || state.vdom || state.hyperscript)) ||
+    (!value && info.boolean && (state.vue || state.vdom || state.hyperscript))
   ) {
     return
   }
@@ -218,28 +250,28 @@ function addAttribute(props, prop, value, ctx, name) {
   }
 
   // Treat `true` and truthy known booleans.
-  if (info.boolean && ctx.hyperscript) {
+  if (info.boolean && state.hyperscript) {
     value = ''
   }
 
   // VDOM, Vue, and React accept `style` as object.
   if (
     info.property === 'style' &&
     typeof value === 'string' &&
-    (ctx.react || ctx.vue || ctx.vdom)
+    (state.react || state.vue || state.vdom)
   ) {
     value = parseStyle(value, name)
   }
 
   // Vue 3 (used in our tests) doesn’t need this anymore.
   // Some major in the future we can drop Vue 2 support.
   /* c8 ignore next 2 */
-  if (ctx.vue) {
+  if (state.vue) {
     if (info.property !== 'style') subprop = 'attrs'
   } else if (!info.mustUseProperty) {
-    if (ctx.vdom) {
+    if (state.vdom) {
       if (info.property !== 'style') subprop = 'attributes'
-    } else if (ctx.hyperscript) {
+    } else if (state.hyperscript) {
       subprop = 'attrs'
     }
   }
@@ -248,8 +280,8 @@ function addAttribute(props, prop, value, ctx, name) {
     props[subprop] = Object.assign(props[subprop] || {}, {
       [info.attribute]: value
     })
-  } else if (info.space && ctx.react) {
-    props[toReact[info.property] || info.property] = value
+  } else if (info.space && state.react) {
+    props[hastToReact[info.property] || info.property] = value
   } else {
     props[info.attribute] = value
   }
@@ -259,7 +291,9 @@ function addAttribute(props, prop, value, ctx, name) {
  * Check if `h` is `react.createElement`.
  *
  * @param {CreateElementLike} h
+ *   HyperScript function.
  * @returns {boolean}
+ *   Looks like React.
  */
 function react(h) {
   const node = /** @type {unknown} */ (h('div', {}))
@@ -276,7 +310,9 @@ function react(h) {
  * Check if `h` is `hyperscript`.
  *
  * @param {CreateElementLike} h
+ *   HyperScript function.
  * @returns {boolean}
+ *   Looks like `hyperscript`.
  */
 function hyperscript(h) {
   return 'context' in h && 'cleanup' in h
@@ -286,7 +322,9 @@ function hyperscript(h) {
  * Check if `h` is `virtual-dom/h`.
  *
  * @param {CreateElementLike} h
+ *   HyperScript function.
  * @returns {boolean}
+ *   Looks like `virtual-dom`
  */
 function vdom(h) {
   const node = /** @type {unknown} */ (h('div', {}))
@@ -298,7 +336,9 @@ function vdom(h) {
  * Check if `h` is Vue.
  *
  * @param {CreateElementLike} h
+ *   HyperScript function.
  * @returns {boolean}
+ *   Looks like Vue.
  */
 function vue(h) {
   // Vue 3 (used in our tests) doesn’t need this anymore.
@@ -310,9 +350,14 @@ function vue(h) {
 }
 
 /**
+ * Parse a declaration into an object.
+ *
  * @param {string} value
+ *   CSS declarations.
  * @param {string} tagName
+ *   Tag name.
  * @returns {Record<string, string>}
+ *   Properties.
  */
 function parseStyle(value, tagName) {
   /** @type {Record<string, string>} */

package.json

@@ -56,11 +56,11 @@
     "@types/tape": "^4.0.0",
     "@types/virtual-dom": "^2.0.0",
     "c8": "^7.0.0",
+    "hast-util-from-html": "^1.0.0",
     "hyperscript": "^2.0.0",
     "prettier": "^2.0.0",
     "react": "^18.0.0",
     "react-dom": "^18.0.0",
-    "rehype": "^12.0.0",
     "remark-cli": "^11.0.0",
     "remark-preset-wooorm": "^9.0.0",
     "tape": "^5.0.0",