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

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>
   )

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 = {

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}

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}

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}

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',
+  },
 }

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<

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

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'

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

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