Add support for async plugins

This commit adds 2 new components that support
turning markdown into react nodes,
asynchronously.
There are different ways to support async things in React.
Component with hooks only run on the client.
Components yielding promises are not supported on the client.
To support different scenarios and the different ways the future
could develop,
these choices are made explicit to users.
Users can choose whether `MarkdownAsync` or `MarkdownHooks` fits
their use case.
ClosesGH-680.
ClosesGH-682.
ClosesGH-890.
ClosesGH-891.
Reviewed-by: Christian Murphy <christian.murphy.42@gmail.com>
Reviewed-by: Remco Haszing <remcohaszing@gmail.com>

Author: wooorm

index.js

@@ -6,4 +6,9 @@
  * @typedef {import('./lib/index.js').UrlTransform} UrlTransform
  */
 
-export{Markdownasdefault,defaultUrlTransform}from'./lib/index.js'
+export{
+MarkdownAsync,
+MarkdownHooks,
+Markdownasdefault,
+defaultUrlTransform
+}from'./lib/index.js'

lib/index.js

@@ -1,9 +1,10 @@
 /**
  * @import {Element, ElementContent, Nodes, Parents, Root} from 'hast'
+ * @import {Root as MdastRoot} from 'mdast'
  * @import {ComponentProps, ElementType, ReactElement} from 'react'
  * @import {Options as RemarkRehypeOptions} from 'remark-rehype'
  * @import {BuildVisitor} from 'unist-util-visit'
- * @import {PluggableList} from 'unified'
+ * @import {PluggableList, Processor} from 'unified'
  */
 
 /**
@@ -95,6 +96,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'
 importremarkParsefrom'remark-parse'
 importremarkRehypefrom'remark-rehype'
 import{unified}from'unified'
@@ -149,33 +151,119 @@ const deprecations = [
 /**
  * Component to render markdown.
  *
+ * This is a synchronous component.
+ * When using async plugins,
+ * see {@linkcode MarkdownAsync} or {@linkcode MarkdownHooks}.
+ *
  * @param {Readonly<Options>} options
  * Props.
  * @returns {ReactElement}
  * React element.
  */
 exportfunctionMarkdown(options){
-constallowedElements=options.allowedElements
-constallowElement=options.allowElement
-constchildren=options.children||''
-constclassName=options.className
-constcomponents=options.components
-constdisallowedElements=options.disallowedElements
+constprocessor=createProcessor(options)
+constfile=createFile(options)
+returnpost(processor.runSync(processor.parse(file),file),options)
+}
+
+/**
+ * Component to render markdown with support for async plugins
+ * through async/await.
+ *
+ * Components returning promises are supported on the server.
+ * For async support on the client,
+ * see {@linkcode MarkdownHooks}.
+ *
+ * @param {Readonly<Options>} options
+ * Props.
+ * @returns {Promise<ReactElement>}
+ * Promise to a React element.
+ */
+exportasyncfunctionMarkdownAsync(options){
+constprocessor=createProcessor(options)
+constfile=createFile(options)
+consttree=awaitprocessor.run(processor.parse(file),file)
+returnpost(tree,options)
+}
+
+/**
+ * Component to render markdown with support for async plugins through hooks.
+ *
+ * This uses `useEffect` and `useState` hooks.
+ * Hooks run on the client and do not immediately render something.
+ * For async support on the server,
+ * see {@linkcode MarkdownAsync}.
+ *
+ * @param {Readonly<Options>} options
+ * Props.
+ * @returns {ReactElement}
+ * React element.
+ */
+exportfunctionMarkdownHooks(options){
+constprocessor=createProcessor(options)
+const[error,setError]=useState(
+/** @type {Error | undefined} */(undefined)
+)
+const[tree,setTree]=useState(/** @type {Root | undefined} */(undefined))
+
+useEffect(
+/* c8 ignore next 7 -- hooks are client-only. */
+function(){
+constfile=createFile(options)
+processor.run(processor.parse(file),file,function(error,tree){
+setError(error)
+setTree(tree)
+})
+},
+[
+options.children,
+options.rehypePlugins,
+options.remarkPlugins,
+options.remarkRehypeOptions
+]
+)
+
+/* c8 ignore next -- hooks are client-only. */
+if(error)throwerror
+
+/* c8 ignore next -- hooks are client-only. */
+returntree ? post(tree,options) : createElement(Fragment)
+}
+
+/**
+ * Set up the `unified` processor.
+ *
+ * @param {Readonly<Options>} options
+ * Props.
+ * @returns {Processor<MdastRoot, MdastRoot, Root, undefined, undefined>}
+ * Result.
+ */
+functioncreateProcessor(options){
 constrehypePlugins=options.rehypePlugins||emptyPlugins
 constremarkPlugins=options.remarkPlugins||emptyPlugins
 constremarkRehypeOptions=options.remarkRehypeOptions
  ? {...options.remarkRehypeOptions, ...emptyRemarkRehypeOptions}
  : emptyRemarkRehypeOptions
-constskipHtml=options.skipHtml
-constunwrapDisallowed=options.unwrapDisallowed
-consturlTransform=options.urlTransform||defaultUrlTransform
 
 constprocessor=unified()
 .use(remarkParse)
 .use(remarkPlugins)
 .use(remarkRehype,remarkRehypeOptions)
 .use(rehypePlugins)
 
+returnprocessor
+}
+
+/**
+ * Set up the virtual file.
+ *
+ * @param {Readonly<Options>} options
+ * Props.
+ * @returns {VFile}
+ * Result.
+ */
+functioncreateFile(options){
+constchildren=options.children||''
 constfile=newVFile()
 
 if(typeofchildren==='string'){
@@ -188,11 +276,27 @@ export function Markdown(options) {
 )
 }
 
-if(allowedElements&&disallowedElements){
-unreachable(
-'Unexpected combined `allowedElements` and `disallowedElements`, expected one or the other'
-)
-}
+returnfile
+}
+
+/**
+ * Process the result from unified some more.
+ *
+ * @param {Nodes} tree
+ * Tree.
+ * @param {Readonly<Options>} options
+ * Props.
+ * @returns {ReactElement}
+ * React element.
+ */
+functionpost(tree,options){
+constallowedElements=options.allowedElements
+constallowElement=options.allowElement
+constcomponents=options.components
+constdisallowedElements=options.disallowedElements
+constskipHtml=options.skipHtml
+constunwrapDisallowed=options.unwrapDisallowed
+consturlTransform=options.urlTransform||defaultUrlTransform
 
 for(constdeprecationofdeprecations){
 if(Object.hasOwn(options,deprecation.from)){
@@ -212,26 +316,28 @@ export function Markdown(options) {
 }
 }
 
-constmdastTree=processor.parse(file)
-/** @type {Nodes} */
-lethastTree=processor.runSync(mdastTree,file)
+if(allowedElements&&disallowedElements){
+unreachable(
+'Unexpected combined `allowedElements` and `disallowedElements`, expected one or the other'
+)
+}
 
 // Wrap in `div` if there’s a class name.
-if(className){
-hastTree={
+if(options.className){
+tree={
 type: 'element',
 tagName: 'div',
-properties: {className},
+properties: {className: options.className},
 // Assume no doctypes.
 children: /** @type {Array<ElementContent>} */(
-hastTree.type==='root' ? hastTree.children : [hastTree]
+tree.type==='root' ? tree.children : [tree]
 )
 }
 }
 
-visit(hastTree,transform)
+visit(tree,transform)
 
-returntoJsxRuntime(hastTree,{
+returntoJsxRuntime(tree,{
  Fragment,
 // @ts-expect-error
 // React components are allowed to return numbers,

package.json

@@ -49,6 +49,7 @@
  ],
 "dependencies": {
 "@types/hast": "^3.0.0",
+"@types/mdast": "^4.0.0",
 "devlop": "^1.0.0",
 "hast-util-to-jsx-runtime": "^2.0.0",
 "html-url-attributes": "^3.0.0",
@@ -65,12 +66,14 @@
 "@types/react": "^19.0.0",
 "@types/react-dom": "^19.0.0",
 "c8": "^10.0.0",
+"concat-stream": "^2.0.0",
 "esbuild": "^0.25.0",
 "eslint-plugin-react": "^7.0.0",
 "prettier": "^3.0.0",
 "react": "^19.0.0",
 "react-dom": "^19.0.0",
 "rehype-raw": "^7.0.0",
+"rehype-starry-night": "^2.0.0",
 "remark-cli": "^12.0.0",
 "remark-gfm": "^4.0.0",
 "remark-preset-wooorm": "^11.0.0",

readme.md

@@ -32,6 +32,8 @@ React component to render markdown.
 *[Use](#use)
 *[API](#api)
 *[`Markdown`](#markdown)
+*[`MarkdownAsync`](#markdownasync)
+*[`MarkdownHooks`](#markdownhooks)
 *[`defaultUrlTransform(url)`](#defaulturltransformurl)
 *[`AllowElement`](#allowelement)
 *[`Components`](#components)
@@ -166,14 +168,58 @@ createRoot(document.body).render(
 
 ## API
 
-This package exports the following identifier:
+This package exports the identifiers
+[`MarkdownAsync`][api-markdown-async],
+[`MarkdownHooks`][api-markdown-hooks],
+and
 [`defaultUrlTransform`][api-default-url-transform].
 The default export is [`Markdown`][api-markdown].
 
 ### `Markdown`
 
 Component to render markdown.
 
+This is a synchronous component.
+When using async plugins,
+see [`MarkdownAsync`][api-markdown-async] or
+[`MarkdownHooks`][api-markdown-hooks].
+
+###### Parameters
+
+*`options` ([`Options`][api-options])
+ — props
+
+###### Returns
+
+React element (`JSX.Element`).
+
+### `MarkdownAsync`
+
+Component to render markdown with support for async plugins
+through async/await.
+
+Components returning promises are supported on the server.
+For async support on the client,
+see [`MarkdownHooks`][api-markdown-hooks].
+
+###### Parameters
+
+*`options` ([`Options`][api-options])
+ — props
+
+###### Returns
+
+Promise to a React element (`Promise<JSX.Element>`).
+
+### `MarkdownHooks`
+
+Component to render markdown with support for async plugins through hooks.
+
+This uses `useEffect` and `useState` hooks.
+Hooks run on the client and do not immediately render something.
+For async support on the server,
+see [`MarkdownAsync`][api-markdown-async].
+
 ###### Parameters
 
 *`options` ([`Options`][api-options])
@@ -779,6 +825,10 @@ abide by its terms.
 
 [api-markdown]: #markdown
 
+[api-markdown-async]: #markdownasync
+
+[api-markdown-hooks]: #markdownhooks
+
 [api-options]: #options
 
 [api-url-transform]: #urltransform