fix(richtext-lexical): drag/drop image into rich text fails when a field name matches the collection slug (#16409)

## Summary

Backport of #16397 to 3.x.

When a top-level rich text field has the same `name` as the collection's
`slug`, dragging or pasting an image into the editor opens a blank bulk
upload drawer. The lexical field and the document layout both mount a
`BulkUploadProvider`; when the field path equals the collection slug
they compute the same drawer slug and render two drawers for it, one
with empty state (blank), which is what the user sees.

The fix is a 1-line change: namespace the lexical field's nested
`BulkUploadProvider` with a `lexical-` prefix so its drawer slug can
never collide with the document-level provider.

```diff
- <BulkUploadProvider drawerSlugPrefix={path}>
+ <BulkUploadProvider drawerSlugPrefix={`lexical-${path}`}>
```

The rest of the diff is a new e2e test.

## Test plan

Added
`test/lexical/collections/LexicalSlugFieldNameCollision/e2e.spec.ts`,
which asserts that dropping a file into a rich text editor opens exactly
one bulk upload drawer when the field name equals the collection slug.
Verified that the test fails without the production change (`Expected:
1, Received: 2`) and passes with it.

Co-authored-by: German Jablonski <GermanJablo@users.noreply.github.com>

Author: GermanJablo

packages/richtext-lexical/src/field/Field.tsx

@@ -213,8 +213,9 @@ const RichTextComponent: React.FC<
         <ErrorBoundary fallbackRender={fallbackRender} onReset={() => {}}>
           {BeforeInput}
           {/* Lexical may be in a drawer. We need to define another BulkUploadProvider to ensure that the bulk upload drawer
-          is rendered in the correct depth (not displayed *behind* the current drawer)*/}
-          <BulkUploadProvider drawerSlugPrefix={path}>
+           * is rendered in the correct depth (not displayed *behind* the current drawer).
+           * The `lexical-` prefix prevents drawer-slug collisions with non-lexical `BulkUploadProvider`s up the tree. */}
+          <BulkUploadProvider drawerSlugPrefix={`lexical-${path}`}>
             <LexicalProvider
               composerKey={pathWithEditDepth}
               editorConfig={editorConfig}

test/lexical/baseConfig.ts

@@ -30,6 +30,7 @@ import {
 } from './collections/LexicalNestedBlocks/index.js'
 import { LexicalObjectReferenceBugCollection } from './collections/LexicalObjectReferenceBug/index.js'
 import { LexicalRelationshipsFields } from './collections/LexicalRelationships/index.js'
+import { LexicalSlugFieldNameCollision } from './collections/LexicalSlugFieldNameCollision/index.js'
 import { LexicalViews } from './collections/LexicalViews/index.js'
 import { LexicalViewsFrontend } from './collections/LexicalViewsFrontend/index.js'
 import { LexicalViewsNested } from './collections/LexicalViewsNested/index.js'
@@ -74,6 +75,7 @@ export const baseConfig: Partial<Config> = {
     LexicalInBlock,
     LexicalAccessControl,
     LexicalRelationshipsFields,
+    LexicalSlugFieldNameCollision,
     LexicalNestedBlocks,
     RichTextFields,
     TextFields,

test/lexical/collections/LexicalSlugFieldNameCollision/e2e.spec.ts

@@ -0,0 +1,62 @@
+import { expect, test } from '@playwright/test'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+import type { PayloadTestSDK } from '../../../__helpers/shared/sdk/index.js'
+import type { Config } from '../../payload-types.js'
+
+import { ensureCompilationIsDone } from '../../../__helpers/e2e/helpers.js'
+import { AdminUrlUtil } from '../../../__helpers/shared/adminUrlUtil.js'
+import { initPayloadE2ENoConfig } from '../../../__helpers/shared/initPayloadE2ENoConfig.js'
+import { TEST_TIMEOUT_LONG } from '../../../playwright.config.js'
+import { lexicalSlugFieldNameCollisionSlug } from '../../slugs.js'
+import { LexicalHelpers } from '../utils.js'
+
+const filename = fileURLToPath(import.meta.url)
+const currentFolder = path.dirname(filename)
+const dirname = path.resolve(currentFolder, '../../')
+
+let payload: PayloadTestSDK<Config>
+let serverURL: string
+
+const { beforeAll, beforeEach, describe } = test
+
+// Repro: dropping an image mounts two bulk upload drawers for the same slug,
+// one blank, when a top-level rich text field name equals the collection slug.
+describe('Lexical: collection slug equals top-level field name', () => {
+  let lexical: LexicalHelpers
+
+  beforeAll(async ({ browser }, testInfo) => {
+    testInfo.setTimeout(TEST_TIMEOUT_LONG)
+    process.env.SEED_IN_CONFIG_ONINIT = 'false'
+    ;({ payload, serverURL } = await initPayloadE2ENoConfig<Config>({ dirname }))
+
+    const page = await browser.newPage()
+    await ensureCompilationIsDone({ page, serverURL })
+    await page.close()
+  })
+
+  beforeEach(async ({ page }) => {
+    const url = new AdminUrlUtil(serverURL, lexicalSlugFieldNameCollisionSlug)
+    lexical = new LexicalHelpers(page)
+    await page.goto(url.create)
+    await lexical.editor.first().focus()
+  })
+
+  test('drag/drop image opens exactly one bulk upload drawer when a field name matches the collection slug', async ({
+    page,
+  }) => {
+    const filePath = path.resolve(dirname, './collections/Upload/payload.jpg')
+
+    await lexical.dropFile({ filePath })
+
+    await expect(page.locator('.bulk-upload--actions-bar')).toBeVisible()
+
+    // Two providers compute the same drawer slug and both mount a drawer; the
+    // empty one is what the user sees as the blank drawer. Should be exactly 1.
+    const bulkDrawers = page.locator(
+      'dialog[aria-label*="bulk-upload-drawer-slug"][open], dialog[id*="bulk-upload-drawer-slug"][open]',
+    )
+    await expect(bulkDrawers).toHaveCount(1)
+  })
+})

test/lexical/collections/LexicalSlugFieldNameCollision/index.ts

@@ -0,0 +1,23 @@
+import type { CollectionConfig } from 'payload'
+
+import { FixedToolbarFeature, lexicalEditor } from '@payloadcms/richtext-lexical'
+
+import { lexicalSlugFieldNameCollisionSlug } from '../../slugs.js'
+
+// The slug and the rich text field name must stay equal to repro the bug.
+export const LexicalSlugFieldNameCollision: CollectionConfig = {
+  slug: lexicalSlugFieldNameCollisionSlug,
+  labels: {
+    singular: 'Lexical Slug Field Name Collision',
+    plural: 'Lexical Slug Field Name Collision',
+  },
+  fields: [
+    {
+      name: lexicalSlugFieldNameCollisionSlug,
+      type: 'richText',
+      editor: lexicalEditor({
+        features: ({ defaultFeatures }) => [...defaultFeatures, FixedToolbarFeature()],
+      }),
+    },
+  ],
+}

test/lexical/collections/utils.ts

@@ -115,6 +115,47 @@ export class LexicalHelpers {
     return {}
   }
 
+  // Simulates a desktop file drop by firing dragenter/dragover/drop with a
+  // populated DataTransfer, triggering Lexical's `DROP_COMMAND`.
+  async dropFile({ filePath }: { filePath: string }) {
+    const name = path.basename(filePath)
+    const mime = inferMimeFromExt(path.extname(name))
+    const buf = await fs.promises.readFile(filePath)
+    const bytes = Array.from(buf)
+
+    const editor = this.editor.first()
+    await editor.evaluate(
+      (el, p) => {
+        const target = el.querySelector('p, span, br, div') ?? (el as HTMLElement)
+
+        const dt = new DataTransfer()
+        const file = new File([new Uint8Array(p.bytes)], p.name, { type: p.mime })
+        dt.items.add(file)
+
+        const rect = target.getBoundingClientRect()
+        const x = rect.left + Math.max(rect.width / 2, 1)
+        const y = rect.top + Math.max(rect.height / 2, 1)
+
+        const dispatch = (type: 'dragenter' | 'dragover' | 'drop') => {
+          const evt = new DragEvent(type, {
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+            clientX: x,
+            clientY: y,
+            dataTransfer: dt,
+          })
+          target.dispatchEvent(evt)
+        }
+
+        dispatch('dragenter')
+        dispatch('dragover')
+        dispatch('drop')
+      },
+      { bytes, name, mime },
+    )
+  }
+
   async paste(type: 'html' | 'markdown', text: string) {
     await this.page.context().grantPermissions(['clipboard-read', 'clipboard-write'])
 

test/lexical/payload-types.ts

@@ -106,6 +106,7 @@ export interface Config {
     LexicalInBlock: LexicalInBlock;
     'lexical-access-control': LexicalAccessControl;
     'lexical-relationship-fields': LexicalRelationshipField;
+    collision: Collision;
     'lexical-nested-blocks': LexicalNestedBlock;
     'rich-text-fields': RichTextField;
     'text-fields': TextField;
@@ -143,6 +144,7 @@ export interface Config {
     LexicalInBlock: LexicalInBlockSelect<false> | LexicalInBlockSelect<true>;
     'lexical-access-control': LexicalAccessControlSelect<false> | LexicalAccessControlSelect<true>;
     'lexical-relationship-fields': LexicalRelationshipFieldsSelect<false> | LexicalRelationshipFieldsSelect<true>;
+    collision: CollisionSelect<false> | CollisionSelect<true>;
     'lexical-nested-blocks': LexicalNestedBlocksSelect<false> | LexicalNestedBlocksSelect<true>;
     'rich-text-fields': RichTextFieldsSelect<false> | RichTextFieldsSelect<true>;
     'text-fields': TextFieldsSelect<false> | TextFieldsSelect<true>;
@@ -939,6 +941,30 @@ export interface LexicalRelationshipField {
   createdAt: string;
   _status?: ('draft' | 'published') | null;
 }
+/**
+ * This interface was referenced by `Config`'s JSON-Schema
+ * via the `definition` "collision".
+ */
+export interface Collision {
+  id: string;
+  collision?: {
+    root: {
+      type: string;
+      children: {
+        type: any;
+        version: number;
+        [k: string]: unknown;
+      }[];
+      direction: ('ltr' | 'rtl') | null;
+      format: 'left' | 'start' | 'center' | 'right' | 'end' | 'justify' | '';
+      indent: number;
+      version: number;
+    };
+    [k: string]: unknown;
+  } | null;
+  updatedAt: string;
+  createdAt: string;
+}
 /**
  * This interface was referenced by `Config`'s JSON-Schema
  * via the `definition` "lexical-nested-blocks".
@@ -1441,6 +1467,10 @@ export interface PayloadLockedDocument {
         relationTo: 'lexical-relationship-fields';
         value: string | LexicalRelationshipField;
       } | null)
+    | ({
+        relationTo: 'collision';
+        value: string | Collision;
+      } | null)
     | ({
         relationTo: 'lexical-nested-blocks';
         value: string | LexicalNestedBlock;
@@ -1763,6 +1793,15 @@ export interface LexicalRelationshipFieldsSelect<T extends boolean = true> {
   createdAt?: T;
   _status?: T;
 }
+/**
+ * This interface was referenced by `Config`'s JSON-Schema
+ * via the `definition` "collision_select".
+ */
+export interface CollisionSelect<T extends boolean = true> {
+  collision?: T;
+  updatedAt?: T;
+  createdAt?: T;
+}
 /**
  * This interface was referenced by `Config`'s JSON-Schema
  * via the `definition` "lexical-nested-blocks_select".

test/lexical/slugs.ts

@@ -30,6 +30,10 @@ export const lexicalCustomCellSlug = 'lexical-custom-cell'
 export const lexicalNestedBlocksSlug = 'lexical-nested-blocks'
 export const lexicalBenchmarkSlug = 'lexical-benchmark'
 
+// Must match the rich text field name on `LexicalSlugFieldNameCollision` to
+// reproduce the bug; rename both together.
+export const lexicalSlugFieldNameCollisionSlug = 'collision'
+
 export const collectionSlugs = [
   lexicalFieldsSlug,
   lexicalLocalizedFieldsSlug,