Add fallback prop to MarkdownHooks

The `<MarkdownHooks/>` component now supports a new prop named
`fallback`. This fallback is displayed while the initial content hasn’t
loaded yet. The name `fallback` was chosen to match the same prop from
`<Suspense/>`.

Closes GH-897.

Reviewed-by: Titus Wormer <[email protected]>

Author: remcohaszing

index.js

@@ -2,6 +2,7 @@
  * @typedef {import('./lib/index.js').AllowElement} AllowElement
  * @typedef {import('./lib/index.js').Components} Components
  * @typedef {import('./lib/index.js').ExtraProps} ExtraProps
+ * @typedef {import('./lib/index.js').HooksOptions} HooksOptions
  * @typedef {import('./lib/index.js').Options} Options
  * @typedef {import('./lib/index.js').UrlTransform} UrlTransform
  */

lib/index.js

@@ -1,7 +1,7 @@
 /**
  * @import {Element, Nodes, Parents, Root} from 'hast'
  * @import {Root as MdastRoot} from 'mdast'
- * @import {ComponentType, JSX, ReactElement} from 'react'
+ * @import {ComponentType, JSX, ReactElement, ReactNode} from 'react'
  * @import {Options as RemarkRehypeOptions} from 'remark-rehype'
  * @import {BuildVisitor} from 'unist-util-visit'
  * @import {PluggableList, Processor} from 'unified'
@@ -77,6 +77,18 @@
  *   Change URLs (default: `defaultUrlTransform`)
  */
 
+/**
+ * @typedef HooksOptionsOnly
+ *   Configuration specifically for {@linkcode MarkdownHooks}.
+ * @property {ReactNode} [fallback]
+ *   Fallback content to render while the processor processing the markdown.
+ */
+
+/**
+ * @typedef {Options & HooksOptionsOnly} HooksOptions
+ *   Configuration for {@linkcode MarkdownHooks}.
+ */
+
 /**
  * @callback UrlTransform
  *   Transform all URLs.
@@ -94,7 +106,7 @@ import {unreachable} from 'devlop'
 import {toJsxRuntime} from 'hast-util-to-jsx-runtime'
 import {urlAttributes} from 'html-url-attributes'
 import {Fragment, jsx, jsxs} from 'react/jsx-runtime'
-import {createElement, useEffect, useState} from 'react'
+import {useEffect, useState} from 'react'
 import remarkParse from 'remark-parse'
 import remarkRehype from 'remark-rehype'
 import {unified} from 'unified'
@@ -193,10 +205,10 @@ export async function MarkdownAsync(options) {
  * For async support on the server,
  * see {@linkcode MarkdownAsync}.
  *
- * @param {Readonly<Options>} options
+ * @param {Readonly<HooksOptions>} options
  *   Props.
- * @returns {ReactElement}
- *   React element.
+ * @returns {ReactNode}
+ *   React node.
  */
 export function MarkdownHooks(options) {
   const processor = createProcessor(options)
@@ -230,7 +242,7 @@ export function MarkdownHooks(options) {
 
   if (error) throw error
 
-  return tree ? post(tree, options) : createElement(Fragment)
+  return tree ? post(tree, options) : options.fallback
 }
 
 /**

test.jsx

@@ -1149,6 +1149,28 @@ test('MarkdownHooks', async function (t) {
     }
   )
 
+  await t.test(
+    'should support `MarkdownHooks` loading fallback',
+    async function () {
+      const plugin = deferPlugin()
+
+      const {container} = render(
+        <MarkdownHooks
+          children={'a'}
+          fallback="Loading"
+          rehypePlugins={[plugin.plugin]}
+        />
+      )
+
+      assert.equal(container.innerHTML, 'Loading')
+      plugin.resolve()
+      await waitFor(() => {
+        assert.notEqual(container.innerHTML, 'Loading')
+      })
+      assert.equal(container.innerHTML, '<p>a</p>')
+    }
+  )
+
   await t.test('should support `MarkdownHooks` that error', async function () {
     const plugin = deferPlugin()