feat(next): add support for custom collection views

packages/next/src/views/Root/getCustomCollectionViewByRoute.spec.ts

@@ -0,0 +1,199 @@
+import type { AdminViewConfig, SanitizedCollectionConfig } from 'payload'
+
+import { describe, expect, it } from 'vitest'
+
+import { getCustomCollectionViewByRoute } from './getCustomCollectionViewByRoute.js'
+
+type Views = SanitizedCollectionConfig['admin']['components']['views']
+
+const gridView: Views = {
+  grid: {
+    Component: '/components/views/GridView/index.js#GridView',
+    exact: true,
+    path: '/grid',
+  },
+}
+
+const gridViewPrefixMatch: Views = {
+  grid: {
+    Component: '/components/views/GridView/index.js#GridView',
+    exact: false,
+    path: '/grid',
+  },
+}
+
+describe('getCustomCollectionViewByRoute', () => {
+  describe('route matching with default /admin prefix', () => {
+    it('should match a custom view at the correct path', () => {
+      const result = getCustomCollectionViewByRoute({
+        adminRoute: '/admin',
+        baseRoute: '/collections/my-collection',
+        currentRoute: '/admin/collections/my-collection/grid',
+        views: gridView,
+      })
+
+      expect(result.viewKey).toBe('grid')
+      expect(result.view.payloadComponent).toBeDefined()
+    })
+
+    it('should not match when the path segment does not correspond to any custom view', () => {
+      const result = getCustomCollectionViewByRoute({
+        adminRoute: '/admin',
+        baseRoute: '/collections/my-collection',
+        currentRoute: '/admin/collections/my-collection/abc123',
+        views: gridView,
+      })
+
+      expect(result.viewKey).toBeNull()
+      expect(result.view.payloadComponent).toBeUndefined()
+    })
+  })
+
+  describe('route matching with custom adminRoute prefix', () => {
+    it('should match when adminRoute is a non-default prefix', () => {
+      const result = getCustomCollectionViewByRoute({
+        adminRoute: '/cms',
+        baseRoute: '/collections/my-collection',
+        currentRoute: '/cms/collections/my-collection/grid',
+        views: gridView,
+      })
+
+      expect(result.viewKey).toBe('grid')
+      expect(result.view.payloadComponent).toBeDefined()
+    })
+
+    it('should match when adminRoute is /', () => {
+      const result = getCustomCollectionViewByRoute({
+        adminRoute: '/',
+        baseRoute: '/collections/my-collection',
+        currentRoute: '/collections/my-collection/grid',
+        views: gridView,
+      })
+
+      expect(result.viewKey).toBe('grid')
+      expect(result.view.payloadComponent).toBeDefined()
+    })
+  })
+
+  describe('route matching with exact: false (prefix matching)', () => {
+    it('should match a sub-path when exact is false', () => {
+      const result = getCustomCollectionViewByRoute({
+        adminRoute: '/admin',
+        baseRoute: '/collections/my-collection',
+        currentRoute: '/admin/collections/my-collection/grid/detail',
+        views: gridViewPrefixMatch,
+      })
+
+      expect(result.viewKey).toBe('grid')
+      expect(result.view.payloadComponent).toBeDefined()
+    })
+
+    it('should match the exact path when exact is false', () => {
+      const result = getCustomCollectionViewByRoute({
+        adminRoute: '/admin',
+        baseRoute: '/collections/my-collection',
+        currentRoute: '/admin/collections/my-collection/grid',
+        views: gridViewPrefixMatch,
+      })
+
+      expect(result.viewKey).toBe('grid')
+      expect(result.view.payloadComponent).toBeDefined()
+    })
+
+    it('should not match an unrelated path when exact is false', () => {
+      const result = getCustomCollectionViewByRoute({
+        adminRoute: '/admin',
+        baseRoute: '/collections/my-collection',
+        currentRoute: '/admin/collections/my-collection/map',
+        views: gridViewPrefixMatch,
+      })
+
+      expect(result.viewKey).toBeNull()
+      expect(result.view.payloadComponent).toBeUndefined()
+    })
+  })
+
+  describe('edge cases', () => {
+    it('should return no match when views is undefined', () => {
+      const result = getCustomCollectionViewByRoute({
+        adminRoute: '/admin',
+        baseRoute: '/collections/my-collection',
+        currentRoute: '/admin/collections/my-collection/grid',
+        views: undefined,
+      })
+
+      expect(result.viewKey).toBeNull()
+      expect(result.view.payloadComponent).toBeUndefined()
+    })
+
+    it('should not match built-in "edit" or "list" keys', () => {
+      const viewsWithBuiltins: Views = {
+        edit: {
+          default: { Component: '/components/views/Edit/index.js#EditView' },
+        },
+        list: {
+          Component: '/components/views/List/index.js#ListView',
+        },
+      }
+
+      const result = getCustomCollectionViewByRoute({
+        adminRoute: '/admin',
+        baseRoute: '/collections/my-collection',
+        currentRoute: '/admin/collections/my-collection/edit',
+        views: viewsWithBuiltins,
+      })
+
+      expect(result.viewKey).toBeNull()
+    })
+
+    it('should not match a custom view that has no path defined', () => {
+      const viewsWithNoPath: Views = {
+        grid: {
+          Component: '/components/views/GridView/index.js#GridView',
+        } as unknown as AdminViewConfig,
+      }
+
+      const result = getCustomCollectionViewByRoute({
+        adminRoute: '/admin',
+        baseRoute: '/collections/my-collection',
+        currentRoute: '/admin/collections/my-collection/grid',
+        views: viewsWithNoPath,
+      })
+
+      expect(result.viewKey).toBeNull()
+    })
+
+    it('should match the correct view when multiple custom views are defined', () => {
+      const multipleViews: Views = {
+        grid: {
+          Component: '/components/views/GridView/index.js#GridView',
+          exact: true,
+          path: '/grid',
+        },
+        map: {
+          Component: '/components/views/MapView/index.js#MapView',
+          exact: true,
+          path: '/map',
+        },
+      }
+
+      const gridResult = getCustomCollectionViewByRoute({
+        adminRoute: '/admin',
+        baseRoute: '/collections/my-collection',
+        currentRoute: '/admin/collections/my-collection/grid',
+        views: multipleViews,
+      })
+
+      expect(gridResult.viewKey).toBe('grid')
+
+      const mapResult = getCustomCollectionViewByRoute({
+        adminRoute: '/admin',
+        baseRoute: '/collections/my-collection',
+        currentRoute: '/admin/collections/my-collection/map',
+        views: multipleViews,
+      })
+
+      expect(mapResult.viewKey).toBe('map')
+    })
+  })
+})

packages/next/src/views/Root/getCustomCollectionViewByRoute.ts

@@ -0,0 +1,82 @@
+import type {
+  AdminViewConfig,
+  AdminViewServerProps,
+  PayloadComponent,
+  SanitizedCollectionConfig,
+} from 'payload'
+
+import type { ViewFromConfig } from './getRouteData.js'
+
+import { isPathMatchingRoute } from './isPathMatchingRoute.js'
+
+export const getCustomCollectionViewByRoute = ({
+  adminRoute,
+  baseRoute,
+  currentRoute: currentRouteWithAdmin,
+  views,
+}: {
+  adminRoute: string
+  baseRoute: string
+  currentRoute: string
+  views: SanitizedCollectionConfig['admin']['components']['views']
+}): {
+  view: ViewFromConfig
+  viewKey: null | string
+} => {
+  const currentRoute =
+    adminRoute === '/'
+      ? currentRouteWithAdmin
+      : currentRouteWithAdmin.startsWith(adminRoute)
+        ? currentRouteWithAdmin.slice(adminRoute.length)
+        : currentRouteWithAdmin
+
+  if (views && typeof views === 'object') {
+    const foundEntry = Object.entries(views).find(([key, view]) => {
+      // Skip the known collection view types: edit and list
+      if (key === 'edit' || key === 'list') {
+        return false
+      }
+
+      // Type guard: custom views should be AdminViewConfig with path and Component
+      const isAdminViewConfig =
+        typeof view === 'object' &&
+        view !== null &&
+        'path' in view &&
+        'Component' in view &&
+        typeof view.path === 'string'
+
+      if (isAdminViewConfig) {
+        const adminView = view as AdminViewConfig
+        const viewPath = `${baseRoute}${adminView.path}`
+
+        return isPathMatchingRoute({
+          currentRoute,
+          exact: adminView.exact,
+          path: viewPath,
+          sensitive: adminView.sensitive,
+          strict: adminView.strict,
+        })
+      }
+
+      return false
+    })
+
+    if (foundEntry) {
+      const [viewKey, foundViewConfig] = foundEntry
+      const adminView = foundViewConfig as AdminViewConfig
+      return {
+        view: {
+          payloadComponent: adminView.Component as PayloadComponent<AdminViewServerProps>,
+        },
+        viewKey,
+      }
+    }
+  }
+
+  return {
+    view: {
+      Component: null,
+    },
+    viewKey: null,
+  }
+}

packages/next/src/views/Root/getRouteData.ts

@@ -31,6 +31,7 @@ import { ResetPassword, resetPasswordBaseClass } from '../ResetPassword/index.js
 import { UnauthorizedView } from '../Unauthorized/index.js'
 import { Verify, verifyBaseClass } from '../Verify/index.js'
 import { getSubViewActions, getViewActions } from './attachViewActions.js'
+import { getCustomCollectionViewByRoute } from './getCustomCollectionViewByRoute.js'
 import { getCustomViewByKey } from './getCustomViewByKey.js'
 import { getCustomViewByRoute } from './getCustomViewByRoute.js'
 import { getDocumentViewInfo } from './getDocumentViewInfo.js'
@@ -370,32 +371,50 @@ export const getRouteData = ({
 
             viewActions.push(...(collectionConfig.admin.components?.views?.list?.actions || []))
           } else {
-            // Collection Edit Views
-            // --> /collections/:collectionSlug/create
-            // --> /collections/:collectionSlug/:id
-            // --> /collections/:collectionSlug/:id/api
-            // --> /collections/:collectionSlug/:id/versions
-            // --> /collections/:collectionSlug/:id/versions/:versionID
-            routeParams.id = segmentThree === 'create' ? undefined : segmentThree
-            routeParams.versionID = segmentFive
-
-            ViewToRender = {
-              Component: DocumentView,
+            // Check for custom collection views before assuming it's an edit view
+            const baseRoute = `/${segmentOne}/${segmentTwo}`
+            const customCollectionView = getCustomCollectionViewByRoute({
+              adminRoute,
+              baseRoute,
+              currentRoute,
+              views: collectionConfig.admin.components?.views,
+            })
+
+            if (customCollectionView.viewKey && customCollectionView.view.payloadComponent) {
+              // --> /collections/:collectionSlug/:customViewPath
+              ViewToRender = customCollectionView.view
+
+              templateClassName = `collection-${customCollectionView.viewKey}`
+              templateType = 'default'
+              viewType = customCollectionView.viewKey
+            } else {
+              // Collection Edit Views
+              // --> /collections/:collectionSlug/create
+              // --> /collections/:collectionSlug/:id
+              // --> /collections/:collectionSlug/:id/api
+              // --> /collections/:collectionSlug/:id/versions
+              // --> /collections/:collectionSlug/:id/versions/:versionID
+              routeParams.id = segmentThree === 'create' ? undefined : segmentThree
+              routeParams.versionID = segmentFive
+
+              ViewToRender = {
+                Component: DocumentView,
+              }
+
+              templateClassName = `collection-default-edit`
+              templateType = 'default'
+
+              const viewInfo = getDocumentViewInfo([segmentFour, segmentFive])
+              viewType = viewInfo.viewType
+              documentSubViewType = viewInfo.documentSubViewType
+
+              viewActions.push(
+                ...getSubViewActions({
+                  collectionOrGlobal: collectionConfig,
+                  viewKeyArg: documentSubViewType,
+                }),
+              )
             }
-
-            templateClassName = `collection-default-edit`
-            templateType = 'default'
-
-            const viewInfo = getDocumentViewInfo([segmentFour, segmentFive])
-            viewType = viewInfo.viewType
-            documentSubViewType = viewInfo.documentSubViewType
-
-            viewActions.push(
-              ...getSubViewActions({
-                collectionOrGlobal: collectionConfig,
-                viewKeyArg: documentSubViewType,
-              }),
-            )
           }
         }
       } else if (globalConfig) {