feat(richtext-lexical): lexical => JSX converter (#8795)

Example:

```tsx
import React from 'react'
import {
  type JSXConvertersFunction,
  RichText,
} from '@payloadcms/richtext-lexical/react'

const jsxConverters: JSXConvertersFunction = ({ defaultConverters }) => ({
  ...defaultConverters,
  blocks: {
      // myTextBlock is the slug of the block
      myTextBlock: ({ node }) => <div style={{ backgroundColor: 'red' }}>{node.fields.text}</div>,
   },
})

export const MyComponent = ({ lexicalContent }) => {
  return (
    <RichText
      converters={jsxConverters}
      data={data.lexicalWithBlocks as SerializedEditorState}
    />
  )
}
```

Author: AlessioGr

docs/lexical/converters.mdx

@@ -6,14 +6,67 @@ desc: Conversion between lexical, markdown and html
 keywords: lexical, rich text, editor, headless cms, convert, html, mdx, markdown, md, conversion, export
 ---
 
+Lexical saves data in JSON - this is great for storage and flexibility and allows you to easily to convert it to other formats like JSX, HTML or Markdown.
+
+## Lexical => JSX
+
+If you have a React-based frontend, converting lexical to JSX is the recommended way to render rich text content in your frontend. To do that, import the `RichText` component from `@payloadcms/richtext-lexical/react` and pass the lexical content to it:
+
+```tsx
+import React from 'react'
+import { RichText } from '@payloadcms/richtext-lexical/react'
+
+export const MyComponent = ({ lexicalData }) => {
+  return (
+    <RichText data={lexicalData} />
+  )
+}
+```
+
+The `RichText` component will come with the most common serializers built-in, though you can also pass in your own serializers if you need to.
+
+<Banner type="default">
+  The JSX converter expects the input data to be fully populated. When fetching data, ensure the `depth` setting is high enough, to ensure that lexical nodes such as uploads are populated.
+</Banner>
+
+### Converting Lexical Blocks to JSX
+
+In order to convert lexical blocks or inline blocks to JSX, you will have to pass the converter for your block to the RichText component. This converter is not included by default, as Payload doesn't know how to render your custom blocks.
+
+```tsx
+import React from 'react'
+import {
+  type JSXConvertersFunction,
+  RichText,
+} from '@payloadcms/richtext-lexical/react'
+import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
+
+const jsxConverters: JSXConvertersFunction = ({ defaultConverters }) => ({
+  ...defaultConverters,
+  blocks: {
+    // myTextBlock is the slug of the block
+    myTextBlock: ({ node }) => <div style={{ backgroundColor: 'red' }}>{node.fields.text}</div>,
+  },
+})
+
+export const MyComponent = ({ lexicalData }) => {
+  return (
+    <RichText
+      converters={jsxConverters}
+      data={lexicalData.lexicalWithBlocks as SerializedEditorState}
+    />
+  )
+}
+```
+
 ## Lexical => HTML
 
-Lexical saves data in JSON, but can also generate its HTML representation via two main methods:
+If you don't have a React-based frontend, or if you need to send the content to a third-party service, you can convert lexical to HTML. There are two ways to do this:
 
 1. **Outputting HTML from the Collection:** Create a new field in your collection to convert saved JSON content to HTML. Payload generates and outputs the HTML for use in your frontend.
 2. **Generating HTML on any server** Convert JSON to HTML on-demand on the server.
 
-The editor comes with built-in HTML serializers, simplifying the process of converting JSON to HTML.
+In both cases, the conversion needs to happen on a server, as the HTML converter will automatically fetch data for nodes that require it (e.g. uploads and internal links). The editor comes with built-in HTML serializers, simplifying the process of converting JSON to HTML.
 
 ### Outputting HTML from the Collection
 

packages/richtext-lexical/package.json

@@ -30,6 +30,11 @@
       "types": "./src/exports/client/index.ts",
       "default": "./src/exports/client/index.ts"
     },
+    "./react": {
+      "import": "./src/exports/react/index.ts",
+      "types": "./src/exports/react/index.ts",
+      "default": "./src/exports/react/index.ts"
+    },
     "./rsc": {
       "import": "./src/exports/server/rsc.ts",
       "types": "./src/exports/server/rsc.ts",
@@ -355,7 +360,7 @@
     "mdast-util-from-markdown": "2.0.2",
     "mdast-util-mdx-jsx": "3.1.3",
     "micromark-extension-mdx-jsx": "3.0.1",
-    "react-error-boundary": "4.0.13",
+    "react-error-boundary": "4.1.1",
     "ts-essentials": "10.0.3",
     "uuid": "10.0.0"
   },
@@ -413,6 +418,11 @@
         "types": "./dist/exports/client/index.d.ts",
         "default": "./dist/exports/client/index.js"
       },
+      "./react": {
+        "import": "./dist/exports/react/index.js",
+        "types": "./dist/exports/react/index.d.ts",
+        "default": "./dist/exports/react/index.js"
+      },
       "./rsc": {
         "import": "./dist/exports/server/rsc.js",
         "types": "./dist/exports/server/rsc.d.ts",

packages/richtext-lexical/src/exports/react/components/RichText/converter/converters/blockquote.tsx

@@ -0,0 +1,12 @@
+import type { SerializedQuoteNode } from '../../../../../../nodeTypes.js'
+import type { JSXConverters } from '../types.js'
+
+export const BlockquoteJSXConverter: JSXConverters<SerializedQuoteNode> = {
+  quote: ({ node, nodesToJSX }) => {
+    const children = nodesToJSX({
+      nodes: node.children,
+    })
+
+    return <blockquote>{children}</blockquote>
+  },
+}

packages/richtext-lexical/src/exports/react/components/RichText/converter/converters/heading.tsx

@@ -0,0 +1,14 @@
+import type { SerializedHeadingNode } from '../../../../../../nodeTypes.js'
+import type { JSXConverters } from '../types.js'
+
+export const HeadingJSXConverter: JSXConverters<SerializedHeadingNode> = {
+  heading: ({ node, nodesToJSX }) => {
+    const children = nodesToJSX({
+      nodes: node.children,
+    })
+
+    const NodeTag = node.tag
+
+    return <NodeTag>{children}</NodeTag>
+  },
+}

packages/richtext-lexical/src/exports/react/components/RichText/converter/converters/horizontalRule.tsx

@@ -0,0 +1,7 @@
+import type { SerializedHorizontalRuleNode } from '../../../../../../nodeTypes.js'
+import type { JSXConverters } from '../types.js'
+export const HorizontalRuleJSXConverter: JSXConverters<SerializedHorizontalRuleNode> = {
+  horizontalrule: () => {
+    return <hr />
+  },
+}

packages/richtext-lexical/src/exports/react/components/RichText/converter/converters/linebreak.tsx

@@ -0,0 +1,8 @@
+import type { SerializedLineBreakNode } from '../../../../../../nodeTypes.js'
+import type { JSXConverters } from '../types.js'
+
+export const LinebreakJSXConverter: JSXConverters<SerializedLineBreakNode> = {
+  linebreak: () => {
+    return <br />
+  },
+}

packages/richtext-lexical/src/exports/react/components/RichText/converter/converters/link.tsx

@@ -0,0 +1,47 @@
+import type { SerializedAutoLinkNode, SerializedLinkNode } from '../../../../../../nodeTypes.js'
+import type { JSXConverters } from '../types.js'
+
+export const LinkJSXConverter: (args: {
+  internalDocToHref?: (args: { linkNode: SerializedLinkNode }) => string
+}) => JSXConverters<SerializedAutoLinkNode | SerializedLinkNode> = ({ internalDocToHref }) => ({
+  autolink: ({ node, nodesToJSX }) => {
+    const children = nodesToJSX({
+      nodes: node.children,
+    })
+
+    const rel: string | undefined = node.fields.newTab ? 'noopener noreferrer' : undefined
+    const target: string | undefined = node.fields.newTab ? '_blank' : undefined
+
+    return (
+      <a href={node.fields.url} {...{ rel, target }}>
+        {children}
+      </a>
+    )
+  },
+  link: ({ node, nodesToJSX }) => {
+    const children = nodesToJSX({
+      nodes: node.children,
+    })
+
+    const rel: string | undefined = node.fields.newTab ? 'noopener noreferrer' : undefined
+    const target: string | undefined = node.fields.newTab ? '_blank' : undefined
+
+    let href: string = node.fields.url
+    if (node.fields.linkType === 'internal') {
+      if (internalDocToHref) {
+        href = internalDocToHref({ linkNode: node })
+      } else {
+        console.error(
+          'Lexical => JSX converter: Link converter: found internal link, but internalDocToHref is not provided',
+        )
+        href = '#' // fallback
+      }
+    }
+
+    return (
+      <a href={href} {...{ rel, target }}>
+        {children}
+      </a>
+    )
+  },
+})

packages/richtext-lexical/src/exports/react/components/RichText/converter/converters/list.tsx

@@ -0,0 +1,59 @@
+import { v4 as uuidv4 } from 'uuid'
+
+import type { SerializedListItemNode, SerializedListNode } from '../../../../../../nodeTypes.js'
+import type { JSXConverters } from '../types.js'
+
+export const ListJSXConverter: JSXConverters<SerializedListItemNode | SerializedListNode> = {
+  list: ({ node, nodesToJSX }) => {
+    const children = nodesToJSX({
+      nodes: node.children,
+    })
+
+    const NodeTag = node.tag
+
+    return <NodeTag className={`list-${node?.listType}`}>{children}</NodeTag>
+  },
+  listitem: ({ node, nodesToJSX, parent }) => {
+    const hasSubLists = node.children.some((child) => child.type === 'list')
+
+    const children = nodesToJSX({
+      nodes: node.children,
+    })
+
+    if ('listType' in parent && parent?.listType === 'check') {
+      const uuid = uuidv4()
+
+      return (
+        <li
+          aria-checked={node.checked ? 'true' : 'false'}
+          className={`list-item-checkbox${node.checked ? ' list-item-checkbox-checked' : ' list-item-checkbox-unchecked'}${hasSubLists ? ' nestedListItem' : ''}`}
+          // eslint-disable-next-line jsx-a11y/no-noninteractive-element-to-interactive-role
+          role="checkbox"
+          style={{ listStyleType: 'none' }}
+          tabIndex={-1}
+          value={node?.value}
+        >
+          {hasSubLists ? (
+            children
+          ) : (
+            <>
+              <input checked={node.checked} id={uuid} type="checkbox" />
+              <label htmlFor={uuid}>{children}</label>
+              <br />
+            </>
+          )}
+        </li>
+      )
+    } else {
+      return (
+        <li
+          className={hasSubLists ? 'nestedListItem' : ''}
+          style={hasSubLists ? { listStyleType: 'none' } : {}}
+          value={node?.value}
+        >
+          {children}
+        </li>
+      )
+    }
+  },
+}

packages/richtext-lexical/src/exports/react/components/RichText/converter/converters/paragraph.tsx

@@ -0,0 +1,20 @@
+import type { SerializedParagraphNode } from '../../../../../../nodeTypes.js'
+import type { JSXConverters } from '../types.js'
+
+export const ParagraphJSXConverter: JSXConverters<SerializedParagraphNode> = {
+  paragraph: ({ node, nodesToJSX }) => {
+    const children = nodesToJSX({
+      nodes: node.children,
+    })
+
+    if (!children?.length) {
+      return (
+        <p>
+          <br />
+        </p>
+      )
+    }
+
+    return <p>{children}</p>
+  },
+}

packages/richtext-lexical/src/exports/react/components/RichText/converter/converters/table.tsx

@@ -0,0 +1,55 @@
+import type {
+  SerializedTableCellNode,
+  SerializedTableNode,
+  SerializedTableRowNode,
+} from '../../../../../../nodeTypes.js'
+import type { JSXConverters } from '../types.js'
+
+export const TableJSXConverter: JSXConverters<
+  SerializedTableCellNode | SerializedTableNode | SerializedTableRowNode
+> = {
+  table: ({ node, nodesToJSX }) => {
+    const children = nodesToJSX({
+      nodes: node.children,
+    })
+    return (
+      <table className="lexical-table" style={{ borderCollapse: 'collapse' }}>
+        <tbody>{children}</tbody>
+      </table>
+    )
+  },
+  tablecell: ({ node, nodesToJSX }) => {
+    const children = nodesToJSX({
+      nodes: node.children,
+    })
+
+    const TagName = node.headerState > 0 ? 'th' : 'td' // Use capital letter to denote a component
+    const headerStateClass = `lexical-table-cell-header-${node.headerState}`
+    const style = {
+      backgroundColor: node.backgroundColor || undefined, // Use undefined to avoid setting the style property if not needed
+      border: '1px solid #ccc',
+      padding: '8px',
+    }
+
+    // Note: JSX does not support setting attributes directly as strings, so you must convert the colSpan and rowSpan to numbers
+    const colSpan = node.colSpan && node.colSpan > 1 ? node.colSpan : undefined
+    const rowSpan = node.rowSpan && node.rowSpan > 1 ? node.rowSpan : undefined
+
+    return (
+      <TagName
+        className={`lexical-table-cell ${headerStateClass}`}
+        colSpan={colSpan} // colSpan and rowSpan will only be added if they are not null
+        rowSpan={rowSpan}
+        style={style}
+      >
+        {children}
+      </TagName>
+    )
+  },
+  tablerow: ({ node, nodesToJSX }) => {
+    const children = nodesToJSX({
+      nodes: node.children,
+    })
+    return <tr className="lexical-table-row">{children}</tr>
+  },
+}