feat(richtext-lexical): new HTML converter (#11370)

Deprecates the old HTML converter and introduces a new one that functions similarly to our Lexical => JSX converter.
The old converter had the following limitations:

- It imported the entire lexical bundle
- It was challenging to implement. The sanitized lexical editor config had to be passed in as an argument, which was difficult to obtain
- It only worked on the server

This new HTML converter is lightweight, user-friendly, and works on both server and client. Instead of retrieving HTML converters from the editor config, they can be explicitly provided to the converter function.

By default, the converter expects populated data to function properly. If you need to use unpopulated data (e.g., when running it from a hook), you also have the option to use the async HTML converter, exported from `@payloadcms/richtext-lexical/html-async`, and provide a `populate` function - this function will then be used to dynamically populate nodes during the conversion process.

## Example 1 - generating HTML in your frontend

```tsx
'use client'

import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
import { convertLexicalToHTML } from '@payloadcms/richtext-lexical/html'

import React from 'react'

export const MyComponent = ({ data }: { data: SerializedEditorState }) => {
  const html = convertLexicalToHTML({ data })

  return <div dangerouslySetInnerHTML={{ __html: html }} />
}
```

## Example - converting Lexical Blocks

```tsx
'use client'

import type { MyInlineBlock, MyTextBlock } from '@/payload-types'
import type {
  DefaultNodeTypes,
  SerializedBlockNode,
  SerializedInlineBlockNode,
} from '@payloadcms/richtext-lexical'
import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'

import {
  convertLexicalToHTML,
  type HTMLConvertersFunction,
} from '@payloadcms/richtext-lexical/html'
import React from 'react'

type NodeTypes =
  | DefaultNodeTypes
  | SerializedBlockNode<MyTextBlock>
  | SerializedInlineBlockNode<MyInlineBlock>

const htmlConverters: HTMLConvertersFunction<NodeTypes> = ({ defaultConverters }) => ({
  ...defaultConverters,
  blocks: {
    // Each key should match your block's slug
    myTextBlock: ({ node, providedCSSString }) =>
      `<div style="background-color: red;${providedCSSString}">${node.fields.text}</div>`,
  },
  inlineBlocks: {
    // Each key should match your inline block's slug
    myInlineBlock: ({ node, providedStyleTag }) =>
      `<span${providedStyleTag}>${node.fields.text}</span$>`,
  },
})

export const MyComponent = ({ data }: { data: SerializedEditorState }) => {
  const html = convertLexicalToHTML({
    converters: htmlConverters,
    data,
  })

  return <div dangerouslySetInnerHTML={{ __html: html }} />
}
```

## Example 3 - outputting HTML from the collection

```ts
import type { HTMLConvertersFunction } from '@payloadcms/richtext-lexical/html'
import type { MyTextBlock } from '@/payload-types.js'
import type { CollectionConfig } from 'payload'

import {
  BlocksFeature,
  type DefaultNodeTypes,
  lexicalEditor,
  lexicalHTMLField,
  type SerializedBlockNode,
} from '@payloadcms/richtext-lexical'

const Pages: CollectionConfig = {
  slug: 'pages',
  fields: [
    {
      name: 'nameOfYourRichTextField',
      type: 'richText',
      editor: lexicalEditor(),
    },
    lexicalHTMLField({
      htmlFieldName: 'nameOfYourRichTextField_html',
      lexicalFieldName: 'nameOfYourRichTextField',
    }),
    {
      name: 'customRichText',
      type: 'richText',
      editor: lexicalEditor({
        features: ({ defaultFeatures }) => [
          ...defaultFeatures,
          BlocksFeature({
            blocks: [
              {
                interfaceName: 'MyTextBlock',
                slug: 'myTextBlock',
                fields: [
                  {
                    name: 'text',
                    type: 'text',
                  },
                ],
              },
            ],
          }),
        ],
      }),
    },
    lexicalHTMLField({
      htmlFieldName: 'customRichText_html',
      lexicalFieldName: 'customRichText',
      // can pass in additional converters or override default ones
      converters: (({ defaultConverters }) => ({
        ...defaultConverters,
        blocks: {
          myTextBlock: ({ node, providedCSSString }) =>
            `<div style="background-color: red;${providedCSSString}">${node.fields.text}</div>`,
        },
      })) as HTMLConvertersFunction<DefaultNodeTypes | SerializedBlockNode<MyTextBlock>>,
    }),
  ],
}
```

Author: AlessioGr

docs/rich-text/converters.mdx

@@ -2,8 +2,8 @@
 title: Lexical Converters
 label: Converters
 order: 20
-desc: Conversion between lexical, markdown and html
-keywords: lexical, rich text, editor, headless cms, convert, html, mdx, markdown, md, conversion, export
+desc: Conversion between lexical, markdown, jsx and html
+keywords: lexical, rich text, editor, headless cms, convert, html, mdx, markdown, md, conversion, export, jsx
 ---
 
 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.
@@ -74,20 +74,28 @@ To convert Lexical Blocks or Inline Blocks to JSX, pass the converter for your b
 
 ```tsx
 'use client'
-import type { MyInlineBlock, MyTextBlock } from '@/payload-types'
-import type { DefaultNodeTypes, SerializedBlockNode } from '@payloadcms/richtext-lexical'
+import type { MyInlineBlock, MyNumberBlock, MyTextBlock } from '@/payload-types'
+import type {
+  DefaultNodeTypes,
+  SerializedBlockNode,
+  SerializedInlineBlockNode,
+} from '@payloadcms/richtext-lexical'
 import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
 
 import { type JSXConvertersFunction, RichText } from '@payloadcms/richtext-lexical/react'
 import React from 'react'
 
 // Extend the default node types with your custom blocks for full type safety
-type NodeTypes = DefaultNodeTypes | SerializedBlockNode<MyInlineBlock | MyTextBlock>
+type NodeTypes =
+  | DefaultNodeTypes
+  | SerializedBlockNode<MyNumberBlock | MyTextBlock>
+  | SerializedInlineBlockNode<MyInlineBlock>
 
 const jsxConverters: JSXConvertersFunction<NodeTypes> = ({ defaultConverters }) => ({
   ...defaultConverters,
   blocks: {
     // Each key should match your block's slug
+    myNumberBlock: ({ node }) => <div>{node.fields.number}</div>,
     myTextBlock: ({ node }) => <div style={{ backgroundColor: 'red' }}>{node.fields.text}</div>,
   },
   inlineBlocks: {
@@ -155,182 +163,220 @@ export const MyComponent: React.FC<{
 
 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.
 
-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.
+1. **Generating HTML in your frontend** Convert JSON to HTML on-demand wherever you need it (Recommended).
+2. **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. This is not recommended, as this approach adds additional overhead to the Payload API and may not work with live preview.
 
-### Outputting HTML from the Collection
+### Generating HTML in your frontend
 
-To add HTML generation directly within the collection, follow the example below:
+If you wish to convert JSON to HTML ad-hoc, use the `convertLexicalToHTML` function exported from `@payloadcms/richtext-lexical/html`:
 
-```ts
-import type { CollectionConfig } from 'payload'
+```tsx
+'use client'
 
-import { HTMLConverterFeature, lexicalEditor, lexicalHTML } from '@payloadcms/richtext-lexical'
+import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
+import { convertLexicalToHTML } from '@payloadcms/richtext-lexical/html'
 
-const Pages: CollectionConfig = {
-  slug: 'pages',
-  fields: [
-    {
-      name: 'nameOfYourRichTextField',
-      type: 'richText',
-      editor: lexicalEditor({
-        features: ({ defaultFeatures }) => [
-          ...defaultFeatures,
-          // The HTMLConverter Feature is the feature which manages the HTML serializers.
-          // If you do not pass any arguments to it, it will use the default serializers.
-          HTMLConverterFeature({}),
-        ],
-      }),
-    },
-    lexicalHTML('nameOfYourRichTextField', { name: 'nameOfYourRichTextField_html' }),
-  ],
+import React from 'react'
+
+export const MyComponent = ({ data }: { data: SerializedEditorState }) => {
+  const html = convertLexicalToHTML({ data })
+
+  return <div dangerouslySetInnerHTML={{ __html: html }} />
 }
 ```
 
-The `lexicalHTML()` function creates a new field that automatically converts the referenced lexical richText field into HTML through an afterRead hook.
+### Generating HTML in your frontend with dynamic population
 
-### Generating HTML anywhere on the server
+The default `convertLexicalToHTML` function does not populate data for nodes like uploads or links - it expects you to pass in the fully populated data. If you want the converter to dynamically populate those nodes as they are encountered, you have to use the async version of the converter, imported from `@payloadcms/richtext-lexical/html-async`, and pass in the `populate` function:
 
-If you wish to convert JSON to HTML ad-hoc, use the `convertLexicalToHTML` function:
+```tsx
+'use client'
 
-```ts
-import { consolidateHTMLConverters, convertLexicalToHTML } from '@payloadcms/richtext-lexical'
+import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
 
+import { getRestPopulateFn } from '@payloadcms/richtext-lexical/client'
+import { convertLexicalToHTMLAsync } from '@payloadcms/richtext-lexical/html-async'
+import React, { useEffect, useState } from 'react'
 
-await convertLexicalToHTML({
-  converters: consolidateHTMLConverters({ editorConfig }),
-  data: editorData,
-  payload, // if you have Payload but no req available, pass it in here to enable server-only functionality (e.g. proper conversion of upload nodes)
-  req, // if you have req available, pass it in here to enable server-only functionality (e.g. proper conversion of upload nodes). No need to pass in Payload if req is passed in.
-})
-```
-This method employs `convertLexicalToHTML` from `@payloadcms/richtext-lexical`, which converts the serialized editor state into HTML.
+export const MyComponent = ({ data }: { data: SerializedEditorState }) => {
+  const [html, setHTML] = useState<null | string>(null)
+  useEffect(() => {
+    async function convert() {
+      const html = await convertLexicalToHTMLAsync({
+        data,
+        populate: getRestPopulateFn({
+          apiURL: `http://localhost:3000/api`,
+        }),
+      })
+      setHTML(html)
+    }
 
-Because every `Feature` is able to provide html converters, and because the `htmlFeature` can modify those or provide their own, we need to consolidate them with the default html Converters using the `consolidateHTMLConverters` function.
+    void convert()
+  }, [data])
 
-#### Example: Generating HTML within an afterRead hook
+  return html && <div dangerouslySetInnerHTML={{ __html: html }} />
+}
+```
 
-```ts
-import type { FieldHook } from 'payload'
+Do note that using the REST populate function will result in each node sending a separate request to the REST API, which may be slow for a large amount of nodes. On the server, you can use the payload populate function, which will be more efficient:
 
-import {
-  HTMLConverterFeature,
-  consolidateHTMLConverters,
-  convertLexicalToHTML,
-  defaultEditorConfig,
-  defaultEditorFeatures,
-  sanitizeServerEditorConfig,
-} from '@payloadcms/richtext-lexical'
+```tsx
+import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
 
-const hook: FieldHook = async ({ req, siblingData }) => {
-  const editorConfig = defaultEditorConfig
+import { getPayloadPopulateFn } from '@payloadcms/richtext-lexical'
+import { convertLexicalToHTMLAsync } from '@payloadcms/richtext-lexical/html-async'
+import { getPayload } from 'payload'
+import React from 'react'
 
-  editorConfig.features = [...defaultEditorFeatures, HTMLConverterFeature({})]
+import config from '../../config.js'
 
-  const sanitizedEditorConfig = await sanitizeServerEditorConfig(editorConfig, req.payload.config)
+export const MyRSCComponent = async ({ data }: { data: SerializedEditorState }) => {
+  const payload = await getPayload({
+    config,
+  })
 
-  const html = await convertLexicalToHTML({
-    converters: consolidateHTMLConverters({ editorConfig: sanitizedEditorConfig }),
-    data: siblingData.lexicalSimple,
-    req,
+  const html = await convertLexicalToHTMLAsync({
+    data,
+    populate: await getPayloadPopulateFn({
+      currentDepth: 0,
+      depth: 1,
+      payload,
+    }),
   })
-  return html
+
+  return html && <div dangerouslySetInnerHTML={{ __html: html }} />
 }
 ```
 
-### CSS
+### Converting Lexical Blocks
 
-Payload's lexical HTML converter does not generate CSS for you, but it does add classes to the generated HTML. You can use these classes to style the HTML in your frontend.
+```tsx
+'use client'
 
-Here is some "base" CSS you can use to ensure that nested lists render correctly:
+import type { MyInlineBlock, MyTextBlock } from '@/payload-types'
+import type {
+  DefaultNodeTypes,
+  SerializedBlockNode,
+  SerializedInlineBlockNode,
+} from '@payloadcms/richtext-lexical'
+import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
 
-```css
-/* Base CSS for Lexical HTML */
-.nestedListItem, .list-check {
-  list-style-type: none;
+import {
+  convertLexicalToHTML,
+  type HTMLConvertersFunction,
+} from '@payloadcms/richtext-lexical/html'
+import React from 'react'
+
+type NodeTypes =
+  | DefaultNodeTypes
+  | SerializedBlockNode<MyTextBlock>
+  | SerializedInlineBlockNode<MyInlineBlock>
+
+const htmlConverters: HTMLConvertersFunction<NodeTypes> = ({ defaultConverters }) => ({
+  ...defaultConverters,
+  blocks: {
+    // Each key should match your block's slug
+    myTextBlock: ({ node, providedCSSString }) =>
+      `<div style="background-color: red;${providedCSSString}">${node.fields.text}</div>`,
+  },
+  inlineBlocks: {
+    // Each key should match your inline block's slug
+    myInlineBlock: ({ node, providedStyleTag }) =>
+      `<span${providedStyleTag}>${node.fields.text}</span$>`,
+  },
+})
+
+export const MyComponent = ({ data }: { data: SerializedEditorState }) => {
+  const html = convertLexicalToHTML({
+    converters: htmlConverters,
+    data,
+  })
+
+  return <div dangerouslySetInnerHTML={{ __html: html }} />
 }
 ```
 
-### Creating your own HTML Converter
+### Outputting HTML from the Collection
 
-HTML Converters are typed as `HTMLConverter`, which contains the node type it should handle, and a function that accepts the serialized node from the lexical editor, and outputs the HTML string. Here's the HTML Converter of the Upload node as an example:
+To add HTML generation directly within the collection, follow the example below:
 
 ```ts
-import type { HTMLConverter } from '@payloadcms/richtext-lexical'
-
-const UploadHTMLConverter: HTMLConverter<SerializedUploadNode> = {
-  converter: async ({ node, req }) => {
-    const uploadDocument: {
-      value?: any
-      } = {}
-    if(req) {
-      await populate({
-        id,
-        collectionSlug: node.relationTo,
-        currentDepth: 0,
-        data: uploadDocument,
-        depth: 1,
-        draft: false,
-        key: 'value',
-        overrideAccess: false,
-        req,
-        showHiddenFields: false,
-      })
-    }
-
-    const url = (req?.payload?.config?.serverURL || '') + uploadDocument?.value?.url
+import type { HTMLConvertersFunction } from '@payloadcms/richtext-lexical/html'
+import type { MyTextBlock } from '@/payload-types.js'
+import type { CollectionConfig } from 'payload'
 
-    if (!(uploadDocument?.value?.mimeType as string)?.startsWith('image')) {
-      // Only images can be serialized as HTML
-      return ``
-    }
+import {
+  BlocksFeature,
+  type DefaultNodeTypes,
+  lexicalEditor,
+  lexicalHTMLField,
+  type SerializedBlockNode,
+} from '@payloadcms/richtext-lexical'
 
-    return `<img src="${url}" alt="${uploadDocument?.value?.filename}" width="${uploadDocument?.value?.width}"  height="${uploadDocument?.value?.height}"/>`
-  },
-  nodeTypes: [UploadNode.getType()], // This is the type of the lexical node that this converter can handle. Instead of hardcoding 'upload' we can get the node type directly from the UploadNode, since it's static.
+const Pages: CollectionConfig = {
+  slug: 'pages',
+  fields: [
+    {
+      name: 'nameOfYourRichTextField',
+      type: 'richText',
+      editor: lexicalEditor(),
+    },
+    lexicalHTMLField({
+      htmlFieldName: 'nameOfYourRichTextField_html',
+      lexicalFieldName: 'nameOfYourRichTextField',
+    }),
+    {
+      name: 'customRichText',
+      type: 'richText',
+      editor: lexicalEditor({
+        features: ({ defaultFeatures }) => [
+          ...defaultFeatures,
+          BlocksFeature({
+            blocks: [
+              {
+                interfaceName: 'MyTextBlock',
+                slug: 'myTextBlock',
+                fields: [
+                  {
+                    name: 'text',
+                    type: 'text',
+                  },
+                ],
+              },
+            ],
+          }),
+        ],
+      }),
+    },
+    lexicalHTMLField({
+      htmlFieldName: 'customRichText_html',
+      lexicalFieldName: 'customRichText',
+      // can pass in additional converters or override default ones
+      converters: (({ defaultConverters }) => ({
+        ...defaultConverters,
+        blocks: {
+          myTextBlock: ({ node, providedCSSString }) =>
+            `<div style="background-color: red;${providedCSSString}">${node.fields.text}</div>`,
+        },
+      })) as HTMLConvertersFunction<DefaultNodeTypes | SerializedBlockNode<MyTextBlock>>,
+    }),
+  ],
 }
 ```
 
-As you can see, we have access to all the information saved in the node (for the Upload node, this is `value`and `relationTo`) and we can use that to generate the HTML.
+The `lexicalHTML()` function creates a new field that automatically converts the referenced lexical richText field into HTML through an afterRead hook.
 
-The `convertLexicalToHTML` is part of `@payloadcms/richtext-lexical` automatically handles traversing the editor state and calling the correct converter for each node.
+### CSS
 
-### Embedding the HTML Converter in your Feature
+Payload's lexical HTML converter does not generate CSS for you, but it does add classes to the generated HTML. You can use these classes to style the HTML in your frontend.
 
-You can embed your HTML Converter directly within your custom `ServerFeature`, allowing it to be handled automatically by the `consolidateHTMLConverters` function. Here is an example:
+Here is some "base" CSS you can use to ensure that nested lists render correctly:
 
-```ts
-import { createNode } from '@payloadcms/richtext-lexical'
-import type { FeatureProviderProviderServer } from '@payloadcms/richtext-lexical'
-
-export const UploadFeature: FeatureProviderProviderServer<
-  UploadFeatureProps,
-  UploadFeaturePropsClient
-> = (props) => {
-  /*...*/
-  return {
-    feature: () => {
-      return {
-        nodes: [
-          createNode({
-            converters: {
-              html: yourHTMLConverter, // <= This is where you define your HTML Converter
-            },
-            node: UploadNode,
-            //...
-          }),
-        ],
-        ClientComponent: UploadFeatureClientComponent,
-        clientFeatureProps: clientProps,
-        serverFeatureProps: props,
-        /*...*/
-      }
-    },
-    key: 'upload',
-    serverFeatureProps: props,
-  }
+```css
+/* Base CSS for Lexical HTML */
+.nestedListItem, .list-check {
+  list-style-type: none;
 }
 ```