feat(richtext-lexical): improve lexical types (#6928)

Author: AlessioGr

docs/lexical/converters.mdx

@@ -46,35 +46,55 @@ const Pages: CollectionConfig = {
 
 The `lexicalHTML()` function creates a new field that automatically converts the referenced lexical richText field into HTML through an afterRead hook.
 
-### Generating HTML anywhere on the server:
+### Generating HTML anywhere on the server
 
-If you wish to convert JSON to HTML ad-hoc, use this code snippet:
+If you wish to convert JSON to HTML ad-hoc, use the `convertLexicalToHTML` function:
 
 ```ts
-import type { SerializedEditorState } from 'lexical'
+import { consolidateHTMLConverters, convertLexicalToHTML } from '@payloadcms/richtext-lexical'
+
+
+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.
+
+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.
+
+#### Example: Generating HTML within an afterRead hook
+
+```ts
+import type { FieldHook } from 'payload'
+
 import {
-  type SanitizedEditorConfig,
-  convertLexicalToHTML,
+  HTMLConverterFeature,
   consolidateHTMLConverters,
+  convertLexicalToHTML,
+  defaultEditorConfig,
+  defaultEditorFeatures,
+  sanitizeServerEditorConfig,
 } from '@payloadcms/richtext-lexical'
 
-async function lexicalToHTML(
-  editorData: SerializedEditorState,
-  editorConfig: SanitizedEditorConfig,
-) {
-  return 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.
+const hook: FieldHook = async ({ req, siblingData }) => {
+  const editorConfig = defaultEditorConfig
+
+  editorConfig.features = [...defaultEditorFeatures, HTMLConverterFeature({})]
+
+  const sanitizedEditorConfig = await sanitizeServerEditorConfig(editorConfig, req.payload.config)
+
+  const html = await convertLexicalToHTML({
+    converters: consolidateHTMLConverters({ editorConfig: sanitizedEditorConfig }),
+    data: siblingData.lexicalSimple,
+    req,
   })
+  return html
 }
 ```
 
-This method employs `convertLexicalToHTML` from `@payloadcms/richtext-lexical`, which converts the serialized editor state into 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.
-
 ### CSS
 
 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.
@@ -184,10 +204,11 @@ import { createHeadlessEditor } from '@lexical/headless' // <= make sure this pa
 import { getEnabledNodes, sanitizeServerEditorConfig } from '@payloadcms/richtext-lexical'
 
 const yourEditorConfig // <= your editor config here
+const payloadConfig // <= your payload config here
 
 const headlessEditor = createHeadlessEditor({
   nodes: getEnabledNodes({
-    editorConfig: sanitizeServerEditorConfig(yourEditorConfig),
+    editorConfig: sanitizeServerEditorConfig(yourEditorConfig, payloadConfig),
   }),
 })
 ```
@@ -316,7 +337,7 @@ Convert markdown content to the Lexical editor format with the following:
 import { $convertFromMarkdownString } from '@lexical/markdown'
 import { sanitizeServerEditorConfig } from '@payloadcms/richtext-lexical'
 
-const yourSanitizedEditorConfig = sanitizeServerEditorConfig(yourEditorConfig) // <= your editor config here
+const yourSanitizedEditorConfig = sanitizeServerEditorConfig(yourEditorConfig, payloadConfig) // <= your editor config & payload config here
 const markdown = `# Hello World`
 
 headlessEditor.update(
@@ -344,7 +365,7 @@ import { $convertToMarkdownString } from '@lexical/markdown'
 import { sanitizeServerEditorConfig } from '@payloadcms/richtext-lexical'
 import type { SerializedEditorState } from 'lexical'
 
-const yourSanitizedEditorConfig = sanitizeServerEditorConfig(yourEditorConfig) // <= your editor config here
+const yourSanitizedEditorConfig = sanitizeServerEditorConfig(yourEditorConfig, payloadConfig) // <= your editor config & payload config here
 const yourEditorState: SerializedEditorState // <= your current editor state here
 
 // Import editor state into your headless editor

docs/lexical/overview.mdx

@@ -89,7 +89,7 @@ import { CallToAction } from '../blocks/CallToAction'
 
 {
   editor: lexicalEditor({
-    features: ({ defaultFeatures }) => [
+    features: ({ defaultFeatures, rootFeatures }) => [
       ...defaultFeatures,
       LinkFeature({
         // Example showing how to customize the built-in fields
@@ -134,6 +134,15 @@ import { CallToAction } from '../blocks/CallToAction'
 }
 ```
 
+`features` can be both an array of features, or a function returning an array of features. The function provides the following props:
+
+
+| Prop                  | Description                                                                                                                                                                                                                                           |
+|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **`defaultFeatures`** | This opinionated array contains all "recommended" default features. You can see which features are included in the default features in the table below.                                                                                               |
+| **`rootFeatures`**    | This array contains all features that are enabled in the root richText editor (the one defined in the payload.config.ts). If this field is the root richText editor, or if the root richText editor is not a lexical editor, this array will be empty. |
+
+
 ## Features overview
 
 Here's an overview of all the included features:
@@ -169,3 +178,77 @@ Notice how even the toolbars are features? That's how extensible our lexical edi
 ## Creating your own, custom Feature
 
 You can find more information about creating your own feature in our [building custom feature docs](lexical/building-custom-features).
+
+## TypeScript
+
+Every single piece of saved data is 100% fully-typed within lexical. It provides a type for every single node, which can be imported from `@payloadcms/richtext-lexical` - each type is prefixed with `Serialized`, e.g. `SerializedUploadNode`.
+
+In order to fully type the entire editor JSON, you can use our `TypedEditorState` helper type, which accepts a union of all possible node types as a generic. The reason we do not provide a type which already contains all possible node types is because the possible node types depend on which features you have enabled in your editor. Here is an example:
+
+```ts
+import type {
+  SerializedAutoLinkNode,
+  SerializedBlockNode,
+  SerializedHorizontalRuleNode,
+  SerializedLinkNode,
+  SerializedListItemNode,
+  SerializedListNode,
+  SerializedParagraphNode,
+  SerializedQuoteNode,
+  SerializedRelationshipNode,
+  SerializedTextNode,
+  SerializedUploadNode,
+  TypedEditorState,
+} from '@payloadcms/richtext-lexical'
+
+const editorState: TypedEditorState<
+  | SerializedAutoLinkNode
+  | SerializedBlockNode
+  | SerializedHorizontalRuleNode
+  | SerializedLinkNode
+  | SerializedListItemNode
+  | SerializedListNode
+  | SerializedParagraphNode
+  | SerializedQuoteNode
+  | SerializedRelationshipNode
+  | SerializedTextNode
+  | SerializedUploadNode
+> = {
+  root: {
+    type: 'root',
+    direction: 'ltr',
+    format: '',
+    indent: 0,
+    version: 1,
+    children: [
+      {
+        children: [
+          {
+            detail: 0,
+            format: 0,
+            mode: 'normal',
+            style: '',
+            text: 'Some text. Every property here is fully-typed',
+            type: 'text',
+            version: 1,
+          },
+        ],
+        direction: 'ltr',
+        format: '',
+        indent: 0,
+        type: 'paragraph',
+        textFormat: 0,
+        version: 1,
+      },
+    ],
+  },
+}
+```
+
+This is a type-safe representation of the editor state. Looking at the auto-suggestions of `type` it will show you all the possible node types you can use.
+
+Make sure to only use types exported from `@payloadcms/richtext-lexical`, not from the lexical core packages. We only have control over types we export and can guarantee that those are correct, even though lexical core may export types with identical names.
+
+### Automatic type generation
+
+Lexical does not generate the accurate type definitions for your richText fields for you yet - this will be improved in the future. Currently, it only outputs the rough shape of the editor JSON which you can enhance using type assertions.

packages/richtext-lexical/src/features/blockquote/feature.server.ts

@@ -1,3 +1,6 @@
+import type { SerializedQuoteNode as _SerializedQuoteNode } from '@lexical/rich-text'
+import type { Spread } from 'lexical'
+
 import { QuoteNode } from '@lexical/rich-text'
 
 // eslint-disable-next-line payload/no-imports-from-exports-dir
@@ -8,6 +11,13 @@ import { createNode } from '../typeUtilities.js'
 import { i18n } from './i18n.js'
 import { MarkdownTransformer } from './markdownTransformer.js'
 
+export type SerializedQuoteNode = Spread<
+  {
+    type: 'quote'
+  },
+  _SerializedQuoteNode
+>
+
 export const BlockquoteFeature = createServerFeature({
   feature: {
     ClientFeature: BlockquoteFeatureClient,

packages/richtext-lexical/src/features/blocks/nodes/BlocksNode.tsx

@@ -30,7 +30,9 @@ const BlockComponent = React.lazy(() =>
 
 export type SerializedBlockNode = Spread<
   {
+    children?: never // required so that our typed editor state doesn't automatically add children
     fields: BlockFields
+    type: 'block'
   },
   SerializedDecoratorBlockNode
 >
@@ -102,7 +104,7 @@ export class BlockNode extends DecoratorBlockNode {
   exportJSON(): SerializedBlockNode {
     return {
       ...super.exportJSON(),
-      type: this.getType(),
+      type: 'block',
       fields: this.getFields(),
       version: 2,
     }

packages/richtext-lexical/src/features/converters/html/feature.server.ts

@@ -9,7 +9,7 @@ export type HTMLConverterFeatureProps = {
 }
 
 // This is just used to save the props on the richText field
-export const HTMLConverterFeature = createServerFeature({
+export const HTMLConverterFeature = createServerFeature<HTMLConverterFeatureProps>({
   feature: {},
   key: 'htmlConverter',
 })

packages/richtext-lexical/src/features/horizontalRule/nodes/HorizontalRuleNode.tsx

@@ -6,6 +6,7 @@ import type {
   LexicalCommand,
   LexicalNode,
   SerializedLexicalNode,
+  Spread,
 } from 'lexical'
 
 import { addClassNamesToElement } from '@lexical/utils'
@@ -21,7 +22,13 @@ const HorizontalRuleComponent = React.lazy(() =>
 /**
  * Serialized representation of a horizontal rule node. Serialized = converted to JSON. This is what is stored in the database / in the lexical editor state.
  */
-export type SerializedHorizontalRuleNode = SerializedLexicalNode
+export type SerializedHorizontalRuleNode = Spread<
+  {
+    children?: never // required so that our typed editor state doesn't automatically add children
+    type: 'horizontalrule'
+  },
+  SerializedLexicalNode
+>
 
 export const INSERT_HORIZONTAL_RULE_COMMAND: LexicalCommand<void> = createCommand(
   'INSERT_HORIZONTAL_RULE_COMMAND',

packages/richtext-lexical/src/features/link/nodes/AutoLinkNode.ts

@@ -41,10 +41,16 @@ export class AutoLinkNode extends LinkNode {
     return node
   }
 
+  // @ts-expect-error
   exportJSON(): SerializedAutoLinkNode {
+    const serialized = super.exportJSON()
     return {
-      ...super.exportJSON(),
       type: 'autolink',
+      children: serialized.children,
+      direction: serialized.direction,
+      fields: serialized.fields,
+      format: serialized.format,
+      indent: serialized.indent,
       version: 2,
     }
   }

packages/richtext-lexical/src/features/link/nodes/LinkNode.ts

@@ -129,7 +129,7 @@ export class LinkNode extends ElementNode {
   exportJSON(): SerializedLinkNode {
     const returnObject: SerializedLinkNode = {
       ...super.exportJSON(),
-      type: this.getType(),
+      type: 'link',
       fields: this.getFields(),
       version: 3,
     }

packages/richtext-lexical/src/features/link/nodes/types.ts

@@ -1,4 +1,4 @@
-import type { SerializedElementNode, Spread } from 'lexical'
+import type { SerializedElementNode, SerializedLexicalNode, Spread } from 'lexical'
 
 export type LinkFields = {
   // unknown, custom fields:
@@ -18,11 +18,14 @@ export type LinkFields = {
   url: string
 }
 
-export type SerializedLinkNode = Spread<
+export type SerializedLinkNode<T extends SerializedLexicalNode = SerializedLexicalNode> = Spread<
   {
     fields: LinkFields
     id?: string // optional if AutoLinkNode
+    type: 'link'
   },
-  SerializedElementNode
+  SerializedElementNode<T>
 >
-export type SerializedAutoLinkNode = Omit<SerializedLinkNode, 'id'>
+export type SerializedAutoLinkNode<T extends SerializedLexicalNode = SerializedLexicalNode> = {
+  type: 'autolink'
+} & Omit<SerializedLinkNode<T>, 'id' | 'type'>

packages/richtext-lexical/src/features/lists/checklist/feature.server.ts

@@ -26,7 +26,7 @@ export const ChecklistFeature = createServerFeature({
               }),
               createNode({
                 converters: {
-                  html: ListItemHTMLConverter,
+                  html: ListItemHTMLConverter as any,
                 },
                 node: ListItemNode,
               }),