feat(next): improved lexical richText diffing in version view (#11760)

This replaces our JSON-based richtext diffing with HTML-based richtext
diffing for lexical. It uses [this HTML diff
library](https://github.com/Arman19941113/html-diff) that I then
modified to handle diffing more complex elements like links, uploads and
relationships.

This makes it way easier to spot changes, replacing the lengthy Lexical
JSON with a clean visual diff that shows exactly what's different.

## Before

![CleanShot 2025-03-18 at 13 54
51@2x](https://github.com/user-attachments/assets/811a7c14-d592-4fdc-a1f4-07eeb78255fe)


## After


![CleanShot 2025-03-31 at 18 14
10@2x](https://github.com/user-attachments/assets/efb64da0-4ff8-4965-a458-558a18375c46)
![CleanShot 2025-03-31 at 18 14
26@2x](https://github.com/user-attachments/assets/133652ce-503b-4b86-9c4c-e5c7706d8ea6)

Author: AlessioGr

Diff for: packages/next/src/views/Version/RenderFieldsToDiff/DiffCollapser/index.tsx

@@ -1,11 +1,10 @@
 'use client'
 import type { ClientField } from 'payload'
 
-import { ChevronIcon, Pill, useConfig, useTranslation } from '@payloadcms/ui'
+import { ChevronIcon, FieldDiffLabel, Pill, useConfig, useTranslation } from '@payloadcms/ui'
 import { fieldIsArrayType, fieldIsBlockType } from 'payload/shared'
 import React, { useState } from 'react'
 
-import Label from '../Label/index.js'
 import './index.scss'
 import { countChangedFields, countChangedFieldsInRows } from '../utilities/countChangedFields.js'
 
@@ -100,7 +99,7 @@ export const DiffCollapser: React.FC<Props> = ({
 
   return (
     <div className={baseClass}>
-      <Label>
+      <FieldDiffLabel>
         <button
           aria-label={isCollapsed ? 'Expand' : 'Collapse'}
           className={`${baseClass}__toggle-button`}
@@ -115,7 +114,7 @@ export const DiffCollapser: React.FC<Props> = ({
             {t('version:changedFieldsCount', { count: changeCount })}
           </Pill>
         )}
-      </Label>
+      </FieldDiffLabel>
       <div className={contentClassNames}>{children}</div>
     </div>
   )

Diff for: packages/next/src/views/Version/RenderFieldsToDiff/buildVersionFields.tsx

@@ -1,22 +1,23 @@
 import type { I18nClient } from '@payloadcms/translations'
-import type {
-  BaseVersionField,
-  ClientField,
-  ClientFieldSchemaMap,
-  Field,
-  FieldDiffClientProps,
-  FieldDiffServerProps,
-  FieldTypes,
-  FlattenedBlock,
-  PayloadComponent,
-  PayloadRequest,
-  SanitizedFieldPermissions,
-  VersionField,
-} from 'payload'
 import type { DiffMethod } from 'react-diff-viewer-continued'
 
 import { RenderServerComponent } from '@payloadcms/ui/elements/RenderServerComponent'
 import { dequal } from 'dequal/lite'
+import {
+  type BaseVersionField,
+  type ClientField,
+  type ClientFieldSchemaMap,
+  type Field,
+  type FieldDiffClientProps,
+  type FieldDiffServerProps,
+  type FieldTypes,
+  type FlattenedBlock,
+  MissingEditorProp,
+  type PayloadComponent,
+  type PayloadRequest,
+  type SanitizedFieldPermissions,
+  type VersionField,
+} from 'payload'
 import { fieldIsID, fieldShouldBeLocalized, getUniqueListBy, tabHasName } from 'payload/shared'
 
 import { diffMethods } from './fields/diffMethods.js'
@@ -238,7 +239,24 @@ const buildVersionField = ({
     return null
   }
 
-  const CustomComponent = field?.admin?.components?.Diff ?? customDiffComponents?.[field.type]
+  let CustomComponent = customDiffComponents?.[field.type]
+  if (field?.type === 'richText') {
+    if (!field?.editor) {
+      throw new MissingEditorProp(field) // while we allow disabling editor functionality, you should not have any richText fields defined if you do not have an editor
+    }
+
+    if (typeof field?.editor === 'function') {
+      throw new Error('Attempted to access unsanitized rich text editor.')
+    }
+
+    if (field.editor.CellComponent) {
+      CustomComponent = field.editor.DiffComponent
+    }
+  }
+  if (field?.admin?.components?.Diff) {
+    CustomComponent = field.admin.components.Diff
+  }
+
   const DefaultComponent = diffComponents?.[field.type]
 
   const baseVersionField: BaseVersionField = {

Diff for: packages/next/src/views/Version/RenderFieldsToDiff/fields/Relationship/index.tsx

@@ -7,12 +7,11 @@ import type {
 } from 'payload'
 
 import { getTranslation } from '@payloadcms/translations'
-import { useConfig, useTranslation } from '@payloadcms/ui'
+import { FieldDiffLabel, useConfig, useTranslation } from '@payloadcms/ui'
 import { fieldAffectsData, fieldIsPresentationalOnly, fieldShouldBeLocalized } from 'payload/shared'
 import React from 'react'
 import ReactDiffViewer from 'react-diff-viewer-continued'
 
-import Label from '../../Label/index.js'
 import './index.scss'
 import { diffStyles } from '../styles.js'
 
@@ -169,10 +168,10 @@ export const Relationship: RelationshipFieldDiffClientComponent = ({
 
   return (
     <div className={baseClass}>
-      <Label>
+      <FieldDiffLabel>
         {locale && <span className={`${baseClass}__locale-label`}>{locale}</span>}
         {getTranslation(label, i18n)}
-      </Label>
+      </FieldDiffLabel>
       <ReactDiffViewer
         hideLineNumbers
         newValue={versionToRender}

Diff for: packages/next/src/views/Version/RenderFieldsToDiff/fields/Select/index.tsx

@@ -3,10 +3,9 @@ import type { I18nClient } from '@payloadcms/translations'
 import type { Option, SelectField, SelectFieldDiffClientComponent } from 'payload'
 
 import { getTranslation } from '@payloadcms/translations'
-import { useTranslation } from '@payloadcms/ui'
+import { FieldDiffLabel, useTranslation } from '@payloadcms/ui'
 import React from 'react'
 
-import Label from '../../Label/index.js'
 import './index.scss'
 import { diffStyles } from '../styles.js'
 import { DiffViewer } from './DiffViewer/index.js'
@@ -103,10 +102,10 @@ export const Select: SelectFieldDiffClientComponent = ({
 
   return (
     <div className={baseClass}>
-      <Label>
+      <FieldDiffLabel>
         {locale && <span className={`${baseClass}__locale-label`}>{locale}</span>}
         {'label' in field && getTranslation(field.label || '', i18n)}
-      </Label>
+      </FieldDiffLabel>
       <DiffViewer
         comparisonToRender={comparisonToRender}
         diffMethod={diffMethod}

Diff for: packages/next/src/views/Version/RenderFieldsToDiff/fields/Text/index.tsx

@@ -2,10 +2,9 @@
 import type { TextFieldDiffClientComponent } from 'payload'
 
 import { getTranslation } from '@payloadcms/translations'
-import { useTranslation } from '@payloadcms/ui'
+import { FieldDiffLabel, useTranslation } from '@payloadcms/ui'
 import React from 'react'
 
-import Label from '../../Label/index.js'
 import './index.scss'
 import { diffStyles } from '../styles.js'
 import { DiffViewer } from './DiffViewer/index.js'
@@ -34,12 +33,12 @@ export const Text: TextFieldDiffClientComponent = ({
 
   return (
     <div className={baseClass}>
-      <Label>
+      <FieldDiffLabel>
         {locale && <span className={`${baseClass}__locale-label`}>{locale}</span>}
         {'label' in field &&
           typeof field.label !== 'function' &&
           getTranslation(field.label || '', i18n)}
-      </Label>
+      </FieldDiffLabel>
       <DiffViewer
         comparisonToRender={comparisonToRender}
         diffMethod={diffMethod}

Diff for: packages/next/src/views/Version/RenderFieldsToDiff/fields/styles.ts

@@ -1,4 +1,6 @@
-export const diffStyles = {
+import type { ReactDiffViewerStylesOverride } from 'react-diff-viewer-continued'
+
+export const diffStyles: ReactDiffViewerStylesOverride = {
   diffContainer: {
     minWidth: 'unset',
   },
@@ -26,4 +28,11 @@ export const diffStyles = {
       wordRemovedBackground: 'var(--theme-error-200)',
     },
   },
+  wordAdded: {
+    color: 'var(--theme-success-600)',
+  },
+  wordRemoved: {
+    color: 'var(--theme-error-600)',
+    textDecorationLine: 'line-through',
+  },
 }

Diff for: packages/payload/src/admin/RichText.ts

@@ -5,12 +5,17 @@ import type { JSONSchema4 } from 'json-schema'
 import type { SanitizedCollectionConfig, TypeWithID } from '../collections/config/types.js'
 import type { Config, PayloadComponent, SanitizedConfig } from '../config/types.js'
 import type { ValidationFieldError } from '../errors/ValidationError.js'
-import type { FieldAffectingData, RichTextField, Validate } from '../fields/config/types.js'
+import type {
+  FieldAffectingData,
+  RichTextField,
+  RichTextFieldClient,
+  Validate,
+} from '../fields/config/types.js'
 import type { SanitizedGlobalConfig } from '../globals/config/types.js'
 import type { RequestContext } from '../index.js'
 import type { JsonObject, PayloadRequest, PopulateType } from '../types/index.js'
-import type { RichTextFieldClientProps } from './fields/RichText.js'
-import type { FieldSchemaMap } from './types.js'
+import type { RichTextFieldClientProps, RichTextFieldServerProps } from './fields/RichText.js'
+import type { FieldDiffClientProps, FieldDiffServerProps, FieldSchemaMap } from './types.js'
 
 export type AfterReadRichTextHookArgs<
   TData extends TypeWithID = any,
@@ -248,7 +253,15 @@ export type RichTextAdapter<
   ExtraFieldProperties = any,
 > = {
   CellComponent: PayloadComponent<never>
-  FieldComponent: PayloadComponent<never, RichTextFieldClientProps>
+  /**
+   * Component that will be displayed in the version diff view.
+   * If not provided, richtext content will be diffed as JSON.
+   */
+  DiffComponent?: PayloadComponent<
+    FieldDiffServerProps<RichTextField, RichTextFieldClient>,
+    FieldDiffClientProps<RichTextFieldClient>
+  >
+  FieldComponent: PayloadComponent<RichTextFieldServerProps, RichTextFieldClientProps>
 } & RichTextAdapterBase<Value, AdapterProps, ExtraFieldProperties>
 
 export type RichTextAdapterProvider<

Diff for: packages/payload/src/fields/config/types.ts

@@ -57,7 +57,7 @@ import type {
   EmailFieldLabelServerComponent,
   FieldDescriptionClientProps,
   FieldDescriptionServerProps,
-  FieldDiffClientComponent,
+  FieldDiffClientProps,
   FieldDiffServerProps,
   GroupFieldClientProps,
   GroupFieldLabelClientComponent,
@@ -326,7 +326,7 @@ type Admin = {
   components?: {
     Cell?: PayloadComponent<DefaultServerCellComponentProps, DefaultCellComponentProps>
     Description?: PayloadComponent<FieldDescriptionServerProps, FieldDescriptionClientProps>
-    Diff?: PayloadComponent<FieldDiffServerProps, FieldDiffClientComponent>
+    Diff?: PayloadComponent<FieldDiffServerProps, FieldDiffClientProps>
     Field?: PayloadComponent<FieldClientComponent | FieldServerComponent>
     /**
      * The Filter component has to be a client component

Diff for: packages/richtext-lexical/src/exports/server/rsc.ts

@@ -1,2 +1,3 @@
 export { RscEntryLexicalCell } from '../../cell/rscEntry.js'
+export { LexicalDiffComponent } from '../../field/Diff/index.js'
 export { RscEntryLexicalField } from '../../field/rscEntry.js'

Diff for: packages/richtext-lexical/src/features/converters/lexicalToHtml/async/types.ts

@@ -83,6 +83,7 @@ export type HTMLConvertersAsync<
         : SerializedInlineBlockNode
     >
   }
+  unknown?: HTMLConverterAsync<SerializedLexicalNode>
 }
 
 export type HTMLConvertersFunctionAsync<

Diff for: packages/richtext-lexical/src/features/converters/lexicalToHtml/shared/findConverterForNode.ts

@@ -1,3 +1,4 @@
+/* eslint-disable no-console */
 import type { SerializedLexicalNode } from 'lexical'
 
 import type { SerializedBlockNode, SerializedInlineBlockNode } from '../../../../nodeTypes.js'
@@ -30,7 +31,7 @@ export function findConverterForNode<
     converterForNode = converters?.blocks?.[
       (node as SerializedBlockNode)?.fields?.blockType
     ] as TConverter
-    if (!converterForNode) {
+    if (!converterForNode && !unknownConverter) {
       console.error(
         `Lexical => HTML converter: Blocks converter: found ${(node as SerializedBlockNode)?.fields?.blockType} block, but no converter is provided`,
       )
@@ -39,7 +40,7 @@ export function findConverterForNode<
     converterForNode = converters?.inlineBlocks?.[
       (node as SerializedInlineBlockNode)?.fields?.blockType
     ] as TConverter
-    if (!converterForNode) {
+    if (!converterForNode && !unknownConverter) {
       console.error(
         `Lexical => HTML converter: Inline Blocks converter: found ${(node as SerializedInlineBlockNode)?.fields?.blockType} inline block, but no converter is provided`,
       )

Diff for: packages/richtext-lexical/src/features/converters/lexicalToHtml/sync/types.ts

@@ -71,6 +71,7 @@ export type HTMLConverters<
         : SerializedInlineBlockNode
     >
   }
+  unknown?: HTMLConverter<SerializedLexicalNode>
 }
 
 export type HTMLConvertersFunction<

Diff for: packages/richtext-lexical/src/features/converters/lexicalToJSX/converter/index.tsx

@@ -1,3 +1,4 @@
+/* eslint-disable no-console */
 import type { SerializedEditorState, SerializedLexicalNode } from 'lexical'
 
 import React from 'react'
@@ -51,15 +52,15 @@ export function convertLexicalNodesToJSX({
     let converterForNode: JSXConverter<any> | undefined
     if (node.type === 'block') {
       converterForNode = converters?.blocks?.[(node as SerializedBlockNode)?.fields?.blockType]
-      if (!converterForNode) {
+      if (!converterForNode && !unknownConverter) {
         console.error(
           `Lexical => JSX converter: Blocks converter: found ${(node as SerializedBlockNode)?.fields?.blockType} block, but no converter is provided`,
         )
       }
     } else if (node.type === 'inlineBlock') {
       converterForNode =
         converters?.inlineBlocks?.[(node as SerializedInlineBlockNode)?.fields?.blockType]
-      if (!converterForNode) {
+      if (!converterForNode && !unknownConverter) {
         console.error(
           `Lexical => JSX converter: Inline Blocks converter: found ${(node as SerializedInlineBlockNode)?.fields?.blockType} inline block, but no converter is provided`,
         )

Diff for: packages/richtext-lexical/src/features/converters/lexicalToJSX/converter/types.ts

@@ -66,6 +66,7 @@ export type JSXConverters<
         : SerializedInlineBlockNode
     >
   }
+  unknown?: JSXConverter<SerializedLexicalNode>
 }
 export type SerializedLexicalNodeWithParent = {
   parent?: SerializedLexicalNode

Diff for: packages/richtext-lexical/src/field/Diff/colors.scss

@@ -0,0 +1,35 @@
+@import '../../scss/styles.scss';
+
+@layer payload-default {
+  :root {
+    --diff-delete-pill-bg: var(--theme-error-200);
+    --diff-delete-pill-color: var(--theme-error-600);
+    --diff-delete-pill-border: var(--theme-error-400);
+    --diff-delete-parent-bg: var(--theme-error-100);
+    --diff-delete-parent-color: var(--theme-error-800);
+    --diff-delete-link-color: var(--theme-error-600);
+
+    --diff-create-pill-bg: var(--theme-success-200);
+    --diff-create-pill-color: var(--theme-success-600);
+    --diff-create-pill-border: var(--theme-success-400);
+    --diff-create-parent-bg: var(--theme-success-100);
+    --diff-create-parent-color: var(--theme-success-800);
+    --diff-create-link-color: var(--theme-success-600);
+  }
+
+  html[data-theme='dark'] {
+    --diff-delete-pill-bg: var(--theme-error-200);
+    --diff-delete-pill-color: var(--theme-error-650);
+    --diff-delete-pill-border: var(--theme-error-400);
+    --diff-delete-parent-bg: var(--theme-error-100);
+    --diff-delete-parent-color: var(--theme-error-900);
+    --diff-delete-link-color: var(--theme-error-750);
+
+    --diff-create-pill-bg: var(--theme-success-200);
+    --diff-create-pill-color: var(--theme-success-650);
+    --diff-create-pill-border: var(--theme-success-400);
+    --diff-create-parent-bg: var(--theme-success-100);
+    --diff-create-parent-color: var(--theme-success-900);
+    --diff-create-link-color: var(--theme-success-750);
+  }
+}