fix(ui): encode HTML special characters in version diff view (#15747)

Adds proper HTML encoding for field values displayed in the version
comparison diff view. Special characters like <, >, &, ", and ' are now
correctly rendered as literal text instead of being interpreted as HTML
markup.

- Add escapeDiffHTML and unescapeDiffHTML utilities to HTMLDiff
- Use Unicode placeholders during diffing to preserve diff accuracy
- Apply encoding to Text, Select, and Date diff components
- Add tests for text and JSON fields containing special characters

Author: JarrodMFlesch

packages/next/src/views/Version/RenderFieldsToDiff/fields/Date/index.tsx

@@ -2,17 +2,18 @@
 import type { DateFieldDiffClientComponent } from 'payload'
 
 import {
+  escapeDiffHTML,
   FieldDiffContainer,
   getHTMLDiffComponents,
+  unescapeDiffHTML,
   useConfig,
   useTranslation,
 } from '@payloadcms/ui'
 import { formatDate } from '@payloadcms/ui/shared'
+import React from 'react'
 
 import './index.scss'
 
-import React from 'react'
-
 const baseClass = 'date-diff'
 
 export const DateDiffComponent: DateFieldDiffClientComponent = ({
@@ -45,14 +46,18 @@ export const DateDiffComponent: DateFieldDiffClientComponent = ({
       })
     : ''
 
+  const escapedFromDate = escapeDiffHTML(formattedFromDate)
+  const escapedToDate = escapeDiffHTML(formattedToDate)
+
   const { From, To } = getHTMLDiffComponents({
     fromHTML:
-      `<div class="${baseClass}" data-enable-match="true" data-date="${formattedFromDate}"><p>` +
-      formattedFromDate +
+      `<div class="${baseClass}" data-enable-match="true" data-date="${escapedFromDate}"><p>` +
+      escapedFromDate +
       '</p></div>',
+    postProcess: unescapeDiffHTML,
     toHTML:
-      `<div class="${baseClass}" data-enable-match="true" data-date="${formattedToDate}"><p>` +
-      formattedToDate +
+      `<div class="${baseClass}" data-enable-match="true" data-date="${escapedToDate}"><p>` +
+      escapedToDate +
       '</p></div>',
     tokenizeByCharacter: false,
   })

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

@@ -3,7 +3,13 @@ import type { I18nClient } from '@payloadcms/translations'
 import type { Option, SelectField, SelectFieldDiffClientComponent } from 'payload'
 
 import { getTranslation } from '@payloadcms/translations'
-import { FieldDiffContainer, getHTMLDiffComponents, useTranslation } from '@payloadcms/ui'
+import {
+  escapeDiffHTML,
+  FieldDiffContainer,
+  getHTMLDiffComponents,
+  unescapeDiffHTML,
+  useTranslation,
+} from '@payloadcms/ui'
 import React from 'react'
 
 import './index.scss'
@@ -94,8 +100,9 @@ export const Select: SelectFieldDiffClientComponent = ({
       : ''
 
   const { From, To } = getHTMLDiffComponents({
-    fromHTML: '<p>' + renderedValueFrom + '</p>',
-    toHTML: '<p>' + renderedValueTo + '</p>',
+    fromHTML: '<p>' + escapeDiffHTML(renderedValueFrom) + '</p>',
+    postProcess: unescapeDiffHTML,
+    toHTML: '<p>' + escapeDiffHTML(renderedValueTo) + '</p>',
     tokenizeByCharacter: true,
   })
 

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

@@ -1,20 +1,25 @@
 'use client'
 import type { TextFieldDiffClientComponent } from 'payload'
 
-import { FieldDiffContainer, getHTMLDiffComponents, useTranslation } from '@payloadcms/ui'
+import {
+  escapeDiffHTML,
+  FieldDiffContainer,
+  getHTMLDiffComponents,
+  unescapeDiffHTML,
+  useTranslation,
+} from '@payloadcms/ui'
+import React from 'react'
 
 import './index.scss'
 
-import React from 'react'
-
 const baseClass = 'text-diff'
 
 function formatValue(value: unknown): {
   tokenizeByCharacter: boolean
   value: string
 } {
   if (typeof value === 'string') {
-    return { tokenizeByCharacter: true, value }
+    return { tokenizeByCharacter: true, value: escapeDiffHTML(value) }
   }
   if (typeof value === 'number') {
     return {
@@ -32,7 +37,7 @@ function formatValue(value: unknown): {
   if (value && typeof value === 'object') {
     return {
       tokenizeByCharacter: false,
-      value: `<pre>${JSON.stringify(value, null, 2)}</pre>`,
+      value: `<pre>${escapeDiffHTML(JSON.stringify(value, null, 2))}</pre>`,
     }
   }
 
@@ -72,6 +77,7 @@ export const Text: TextFieldDiffClientComponent = ({
 
   const { From, To } = getHTMLDiffComponents({
     fromHTML: '<p>' + renderedValueFrom + '</p>',
+    postProcess: unescapeDiffHTML,
     toHTML: '<p>' + renderedValueTo + '</p>',
     tokenizeByCharacter,
   })

packages/ui/src/elements/HTMLDiff/escapeHtml.ts

@@ -0,0 +1,49 @@
+// Unicode Private Use Area characters for temporary escaping during diff.
+// These are replaced with HTML entities after the diff is computed.
+const ESCAPE_MAP = {
+  '"': '\uE004',
+  '&': '\uE001',
+  "'": '\uE005',
+  '<': '\uE002',
+  '>': '\uE003',
+} as const
+
+const UNESCAPE_MAP = {
+  '\uE001': '&amp;',
+  '\uE002': '&lt;',
+  '\uE003': '&gt;',
+  '\uE004': '&quot;',
+  '\uE005': '&#39;',
+} as const
+
+/**
+ * Escapes HTML special characters using Unicode placeholders.
+ * These must be converted to HTML entities after diffing using unescapeDiffHTML.
+ */
+export function escapeDiffHTML(value: boolean | null | number | string | undefined): string {
+  if (value == null) {
+    return ''
+  }
+
+  const str = typeof value === 'string' ? value : String(value)
+
+  return str
+    .replace(/&/g, ESCAPE_MAP['&'])
+    .replace(/</g, ESCAPE_MAP['<'])
+    .replace(/>/g, ESCAPE_MAP['>'])
+    .replace(/"/g, ESCAPE_MAP['"'])
+    .replace(/'/g, ESCAPE_MAP["'"])
+}
+
+/**
+ * Converts Unicode placeholder characters to HTML entities.
+ * Call this on the final HTML output after diffing.
+ */
+export function unescapeDiffHTML(html: string): string {
+  return html
+    .replace(/\uE001/g, UNESCAPE_MAP['\uE001'])
+    .replace(/\uE002/g, UNESCAPE_MAP['\uE002'])
+    .replace(/\uE003/g, UNESCAPE_MAP['\uE003'])
+    .replace(/\uE004/g, UNESCAPE_MAP['\uE004'])
+    .replace(/\uE005/g, UNESCAPE_MAP['\uE005'])
+}

packages/ui/src/elements/HTMLDiff/index.tsx

@@ -3,14 +3,22 @@ import React from 'react'
 import { HtmlDiff } from './diff/index.js'
 import './index.scss'
 
+export { escapeDiffHTML, unescapeDiffHTML } from './escapeHtml.js'
+
 const baseClass = 'html-diff'
 
 export const getHTMLDiffComponents = ({
   fromHTML,
+  postProcess,
   toHTML,
   tokenizeByCharacter,
 }: {
   fromHTML: string
+  /**
+   * Optional function to transform the HTML output after diffing.
+   * Useful for converting escape sequences to HTML entities.
+   */
+  postProcess?: (html: string) => string
   toHTML: string
   tokenizeByCharacter?: boolean
 }): {
@@ -21,7 +29,12 @@ export const getHTMLDiffComponents = ({
     tokenizeByCharacter,
   })
 
-  const [oldHTML, newHTML] = diffHTML.getSideBySideContents()
+  let [oldHTML, newHTML] = diffHTML.getSideBySideContents()
+
+  if (postProcess) {
+    oldHTML = postProcess(oldHTML)
+    newHTML = postProcess(newHTML)
+  }
 
   const From = oldHTML ? (
     <div

packages/ui/src/exports/client/index.ts

@@ -76,7 +76,11 @@ export { DeleteMany } from '../../elements/DeleteMany/index.js'
 export { DocumentControls } from '../../elements/DocumentControls/index.js'
 export { Dropzone } from '../../elements/Dropzone/index.js'
 export { documentDrawerBaseClass, useDocumentDrawer } from '../../elements/DocumentDrawer/index.js'
-export { getHTMLDiffComponents } from '../../elements/HTMLDiff/index.js'
+export {
+  escapeDiffHTML,
+  getHTMLDiffComponents,
+  unescapeDiffHTML,
+} from '../../elements/HTMLDiff/index.js'
 export type {
   DocumentDrawerProps,
   DocumentTogglerProps,

packages/ui/src/exports/rsc/index.ts

@@ -2,7 +2,11 @@ export { FieldDiffContainer } from '../../elements/FieldDiffContainer/index.js'
 export { FieldDiffLabel } from '../../elements/FieldDiffLabel/index.js'
 export { FolderTableCell } from '../../elements/FolderView/Cell/index.server.js'
 export { FolderField } from '../../elements/FolderView/FolderField/index.server.js'
-export { getHTMLDiffComponents } from '../../elements/HTMLDiff/index.js'
+export {
+  escapeDiffHTML,
+  getHTMLDiffComponents,
+  unescapeDiffHTML,
+} from '../../elements/HTMLDiff/index.js'
 export { _internal_renderFieldHandler } from '../../forms/fieldSchemasToFormState/serverFunctions/renderFieldServerFn.js'
 export { File } from '../../graphics/File/index.js'
 export { CheckIcon } from '../../icons/Check/index.js'

test/__helpers/e2e/navigateToDiffVersionView.ts

@@ -21,7 +21,7 @@ export async function navigateToDiffVersionView({
   /**
    * If not provided, will attempt to navigate to the latest version's diff view
    */
-  versionID?: string
+  versionID?: number | string
 }) {
   if (versionID) {
     const versionURL = formatAdminURL({

test/versions/e2e.spec.ts

@@ -23,11 +23,12 @@
  */
 
 import type { BrowserContext, Dialog, Page } from '@playwright/test'
+import type { TypeWithID } from 'payload'
 
 import { expect, test } from '@playwright/test'
-import { postsCollectionSlug } from 'admin/slugs.js'
 import { checkFocusIndicators } from '__helpers/e2e/checkFocusIndicators.js'
 import { runAxeScan } from '__helpers/e2e/runAxeScan.js'
+import { postsCollectionSlug } from 'admin/slugs.js'
 import mongoose from 'mongoose'
 import path from 'path'
 import { formatAdminURL, wait } from 'payload/shared'
@@ -36,6 +37,7 @@ import { fileURLToPath } from 'url'
 import type { PayloadTestSDK } from '../__helpers/shared/sdk/index.js'
 import type { Config, Diff } from './payload-types.js'
 
+import { assertNetworkRequests } from '../__helpers/e2e/assertNetworkRequests.js'
 import {
   changeLocale,
   ensureCompilationIsDone,
@@ -47,13 +49,12 @@ import {
   waitForFormReady,
   // throttleTest,
 } from '../__helpers/e2e/helpers.js'
-import { AdminUrlUtil } from '../__helpers/shared/adminUrlUtil.js'
-import { assertNetworkRequests } from '../__helpers/e2e/assertNetworkRequests.js'
 import { navigateToDiffVersionView as _navigateToDiffVersionView } from '../__helpers/e2e/navigateToDiffVersionView.js'
 import { openDocControls } from '../__helpers/e2e/openDocControls.js'
 import { waitForAutoSaveToRunAndComplete } from '../__helpers/e2e/waitForAutoSaveToRunAndComplete.js'
-import { initPayloadE2ENoConfig } from '../__helpers/shared/initPayloadE2ENoConfig.js'
+import { AdminUrlUtil } from '../__helpers/shared/adminUrlUtil.js'
 import { reInitializeDB } from '../__helpers/shared/clearAndSeed/reInitializeDB.js'
+import { initPayloadE2ENoConfig } from '../__helpers/shared/initPayloadE2ENoConfig.js'
 import { POLL_TOPASS_TIMEOUT, TEST_TIMEOUT_LONG } from '../playwright.config.js'
 import { draftWithCustomUnpublishSlug } from './collections/DraftsWithCustomUnpublish.js'
 import { BASE_PATH } from './shared.js'
@@ -78,8 +79,8 @@ import {
   localizedCollectionSlug,
   localizedGlobalSlug,
   postCollectionSlug,
-  versionCollectionSlug,
   textCollectionSlug,
+  versionCollectionSlug,
 } from './slugs.js'
 
 const filename = fileURLToPath(import.meta.url)
@@ -2677,6 +2678,108 @@ describe('Versions', () => {
       const blocks = page.locator('[data-field-path="blocks"]')
       await expect(blocks).toBeVisible()
     })
+
+    test('correctly renders text fields containing HTML special characters', async () => {
+      // Create a document with HTML special characters in a text field
+      const doc = await payload.create({
+        collection: diffCollectionSlug,
+        data: {
+          _status: 'published',
+          text: '<b>bold</b> & "quotes"',
+        },
+      })
+
+      // Update to create a version
+      await payload.update({
+        collection: diffCollectionSlug,
+        id: doc.id,
+        data: {
+          _status: 'published',
+          text: '<script>alert(1)</script>',
+        },
+      })
+
+      const versionDiff = (
+        await payload.findVersions({
+          collection: diffCollectionSlug,
+          depth: 0,
+          limit: 1,
+          where: {
+            parent: { equals: doc.id },
+          },
+        })
+      ).docs[0] as unknown as TypeWithID
+
+      await _navigateToDiffVersionView({
+        adminRoute,
+        serverURL,
+        collectionSlug: diffCollectionSlug,
+        docID: doc.id,
+        versionID: versionDiff.id,
+        page,
+      })
+
+      const text = page.locator('[data-field-path="text"]')
+
+      // Verify that HTML characters are rendered as literal text, not interpreted as HTML
+      await expect(text.locator('.html-diff__diff-old')).toHaveText('<b>bold</b> & "quotes"')
+      await expect(text.locator('.html-diff__diff-new')).toHaveText('<script>alert(1)</script>')
+
+      // Cleanup
+      await payload.delete({ collection: diffCollectionSlug, id: doc.id })
+    })
+
+    test('correctly renders JSON fields containing HTML special characters', async () => {
+      // Create a document with HTML special characters in a JSON field
+      const doc = await payload.create({
+        collection: diffCollectionSlug,
+        data: {
+          _status: 'published',
+          json: { html: '<div class="test">&amp;</div>' },
+        },
+      })
+
+      // Update to create a version
+      await payload.update({
+        collection: diffCollectionSlug,
+        id: doc.id,
+        data: {
+          _status: 'published',
+          json: { html: '<span onclick="alert(1)">click</span>' },
+        },
+      })
+
+      const versionDiff = (
+        await payload.findVersions({
+          collection: diffCollectionSlug,
+          depth: 0,
+          limit: 1,
+          where: {
+            parent: { equals: doc.id },
+          },
+        })
+      ).docs[0] as unknown as TypeWithID
+
+      await _navigateToDiffVersionView({
+        adminRoute,
+        serverURL,
+        collectionSlug: diffCollectionSlug,
+        docID: doc.id,
+        versionID: versionDiff.id,
+        page,
+      })
+
+      const json = page.locator('[data-field-path="json"]')
+
+      // Verify that JSON with HTML characters renders the literal text
+      await expect(json.locator('.html-diff__diff-old')).toContainText('"<div class=\\"test\\">')
+      await expect(json.locator('.html-diff__diff-new')).toContainText(
+        '"<span onclick=\\"alert(1)\\">',
+      )
+
+      // Cleanup
+      await payload.delete({ collection: diffCollectionSlug, id: doc.id })
+    })
   })
 
   describe('Scheduled publish', () => {