fix!: handles custom collection description components (#7789)

## Description

Closes #7784 by properly handling custom collection description
components via `admin.components.Description`. This component was
incorrectly added to the `admin.components.edit` key, and also was never
handled on the front-end. This was especially misleading because the
client-side config had a duplicative key in the proper position.

## Breaking Changes

This PR is only labeled as a breaking change because the key has changed
position within the config. If you were previously defining a custom
description component on a collection, simply move it into the correct
position:

Old:
```ts
{
  admin: {
    components: {
      edit: {
        Description: ''
      }
    }
  }
}
```

New:

```ts
{
  admin: {
    components: {
      Description: ''
    }
  }
}
```

- [x] I have read and understand the
[CONTRIBUTING.md](https://github.com/payloadcms/payload/blob/main/CONTRIBUTING.md)
document in this repository.

## Type of change

- [x] Bug fix (non-breaking change which fixes an issue)
- [x] This change requires a documentation update

## Checklist:

- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] Existing test suite passes locally with my changes
- [x] I have made corresponding changes to the documentation

Author: jacobsfletch

docs/admin/collections.mdx

@@ -31,7 +31,7 @@ The following options are available:
 | **`hidden`**                     | Set to true or a function, called with the current user, returning true to exclude this Collection from navigation and admin routing.                                                                 |
 | **`hooks`**                      | Admin-specific hooks for this Collection. [More details](../hooks/collections).                                                                                                                                        |
 | **`useAsTitle`**                 | Specify a top-level field to use for a document title throughout the Admin Panel. If no field is defined, the ID of the document is used as the title.                                                |
-| **`description`**                | Text or React component to display below the Collection label in the List View to give editors more information.                                                                                      |
+| **`description`**                | Text to display below the Collection label in the List View to give editors more information. Alternatively, you can use the `admin.components.Description` to render a React component. [More details](#components). |
 | **`defaultColumns`**             | Array of field names that correspond to which columns to show by default in this Collection's List View.                                                                                              |
 | **`hideAPIURL`**                 | Hides the "API URL" meta field while editing documents within this Collection.                                                                                                                        |
 | **`enableRichTextLink`**         | The [Rich Text](../fields/rich-text) field features a `Link` element which allows for users to automatically reference related documents within their rich text. Set to `true` by default.         |
@@ -69,7 +69,8 @@ The following options are available:
 | **`beforeList`**           | An array of components to inject _before_ the built-in List View                                                          |
 | **`beforeListTable`**      | An array of components to inject _before_ the built-in List View's table                                                  |
 | **`afterList`**            | An array of components to inject _after_ the built-in List View                                                           |
-| **`afterListTable`**       | An array of components to inject _after_ the built-in List View's table                                                   |
+| **`afterListTable`**       | An array of components to inject _after_ the built-in List View's table
+| **`Description`**          | A component to render below the Collection label in the List View. An alternative to the `admin.description` property. |
 | **`edit.SaveButton`**      | Replace the default Save Button with a Custom Component. [Drafts](../versions/drafts) must be disabled.                                     |
 | **`edit.SaveDraftButton`** | Replace the default Save Draft Button with a Custom Component. [Drafts](../versions/drafts) must be enabled and autosave must be disabled. |
 | **`edit.PublishButton`**   | Replace the default Publish Button with a Custom Component. [Drafts](../versions/drafts) must be enabled.                                  |

packages/next/src/views/List/Default/index.tsx

@@ -13,7 +13,6 @@ import {
   ListSelection,
   Pagination,
   PerPage,
-  PopupList,
   PublishMany,
   RelationshipProvider,
   RenderComponent,
@@ -124,13 +123,9 @@ export const DefaultListView: React.FC = () => {
               {!smallBreak && (
                 <ListSelection label={getTranslation(collectionConfig.labels.plural, i18n)} />
               )}
-              {description && (
+              {(description || Description) && (
                 <div className={`${baseClass}__sub-header`}>
-                  <RenderComponent
-                    Component={ViewDescription}
-                    clientProps={{ description }}
-                    mappedComponent={Description}
-                  />
+                  <ViewDescription Description={Description} description={description} />
                 </div>
               )}
             </ListHeader>

packages/payload/src/bin/generateImportMap/index.ts

@@ -85,6 +85,7 @@ export async function generateImportMap(
   if (shouldLog) {
     console.log('Generating import map')
   }
+
   const importMap: InternalImportMap = {}
   const imports: Imports = {}
 

packages/payload/src/bin/generateImportMap/iterateCollections.ts

@@ -33,8 +33,8 @@ export function iterateCollections({
     addToImportMap(collection.admin?.components?.afterListTable)
     addToImportMap(collection.admin?.components?.beforeList)
     addToImportMap(collection.admin?.components?.beforeListTable)
+    addToImportMap(collection.admin?.components?.Description)
 
-    addToImportMap(collection.admin?.components?.edit?.Description)
     addToImportMap(collection.admin?.components?.edit?.PreviewButton)
     addToImportMap(collection.admin?.components?.edit?.PublishButton)
     addToImportMap(collection.admin?.components?.edit?.SaveButton)

packages/payload/src/collections/config/client.ts

@@ -24,7 +24,6 @@ export type ClientCollectionConfig = {
       beforeList: MappedComponent[]
       beforeListTable: MappedComponent[]
       edit: {
-        Description: MappedComponent
         PreviewButton: MappedComponent
         PublishButton: MappedComponent
         SaveButton: MappedComponent

packages/payload/src/collections/config/types.ts

@@ -250,6 +250,7 @@ export type CollectionAdminOptions = {
    * Custom admin components
    */
   components?: {
+    Description?: EntityDescriptionComponent
     afterList?: CustomComponent[]
     afterListTable?: CustomComponent[]
     beforeList?: CustomComponent[]
@@ -258,8 +259,6 @@ export type CollectionAdminOptions = {
      * Components within the edit view
      */
     edit?: {
-      Description?: EntityDescriptionComponent
-
       /**
        * Replaces the "Preview" button
        */

packages/ui/src/elements/ListDrawer/DrawerContent.tsx

@@ -251,9 +251,13 @@ export const ListDrawerContent: React.FC<ListDrawerProps> = ({
               <XIcon />
             </button>
           </div>
-          {selectedCollectionConfig?.admin?.description && (
+          {(selectedCollectionConfig?.admin?.description ||
+            selectedCollectionConfig?.admin?.components?.Description) && (
             <div className={`${baseClass}__sub-header`}>
-              <ViewDescription description={selectedCollectionConfig.admin.description} />
+              <ViewDescription
+                Description={selectedCollectionConfig.admin?.components?.Description}
+                description={selectedCollectionConfig.admin?.description}
+              />
             </div>
           )}
           {moreThanOneAvailableCollection && (

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

@@ -1,9 +1,10 @@
 'use client'
-import type { DescriptionFunction, StaticDescription } from 'payload'
+import type { DescriptionFunction, MappedComponent, StaticDescription } from 'payload'
 
 import { getTranslation } from '@payloadcms/translations'
 import React from 'react'
 
+import { RenderComponent } from '../../providers/Config/RenderComponent.js'
 import { useTranslation } from '../../providers/Translation/index.js'
 import './index.scss'
 
@@ -12,7 +13,8 @@ export type ViewDescriptionComponent = React.ComponentType<any>
 type Description = DescriptionFunction | StaticDescription | ViewDescriptionComponent | string
 
 export type ViewDescriptionProps = {
-  readonly description?: Description
+  readonly Description?: MappedComponent
+  readonly description?: StaticDescription
 }
 
 export function isComponent(description: Description): description is ViewDescriptionComponent {
@@ -21,11 +23,10 @@ export function isComponent(description: Description): description is ViewDescri
 
 export const ViewDescription: React.FC<ViewDescriptionProps> = (props) => {
   const { i18n } = useTranslation()
-  const { description } = props
+  const { Description, description, ...rest } = props
 
-  if (isComponent(description)) {
-    const Description = description
-    return <Description />
+  if (Description) {
+    return <RenderComponent clientProps={{ description, ...rest }} mappedComponent={Description} />
   }
 
   if (description) {

packages/ui/src/providers/Config/createClientConfig/collections.tsx

@@ -224,21 +224,19 @@ export const createClientCollectionConfig = ({
 
   clientCollection.admin.description = description
 
-  if (collection.admin.components.edit?.Description) {
-    clientCollection.admin.components.edit.Description = createMappedComponent(
-      collection.admin.components.edit.Description,
+  if (collection.admin.components?.Description) {
+    clientCollection.admin.components.Description = createMappedComponent(
+      collection.admin.components.Description,
       {
         clientProps: {
           description,
         },
       },
       undefined,
-      'collection.admin.components.edit.Description',
+      'collection.admin.components.Description',
     )
   }
 
-  clientCollection.admin.description = description
-
   clientCollection.admin.components.views = (
     collection?.admin?.components?.views
       ? deepCopyObjectSimple(collection?.admin?.components?.views)

test/admin/collections/CustomViews1.ts

@@ -6,6 +6,7 @@ export const CustomViews1: CollectionConfig = {
   slug: customViews1CollectionSlug,
   admin: {
     components: {
+      Description: '/components/ViewDescription/index.js#ViewDescription',
       views: {
         // This will override the entire Edit View including all nested views, i.e. `/edit/:id/*`
         // To override one specific nested view, use the nested view's slug as the key