feat: mount live preview to document root (#12860)

Mounts live preview to `../:id` instead `../:id/preview`.

This is a huge win for both UX and a maintainability standpoint.

Here are just a few of those wins:

1. If you edit a document, _then_ decide you want to preview those
changes, you are currently presented with the `LeaveWithoutSaving` modal
and are forced to either save your edits or clear them. This is because
you are being navigated to an entirely new page with it's own form
context. Instead, you should be able to freely navigate back and forth
between the two.
2. If you are an editor who most often uses Live Preview, or you are
editing a collection that typically requires it, you likely want it to
automatically enter live preview mode when you open a document.
Currently, the user has to navigate to the document _first_, then use
the live preview tab. Instead, you should be able to set a preference
and avoid this extra step.
3. Since the inception of Live Preview, we've been maintaining largely
the same code across the default edit view and the live preview view,
which often became out of sync and inconsistent—but they're essentially
doing the same thing. While we could abstract a lot of this out, it is
no longer necessary if the two views are combined into one.

This change does also include some small modifications to UI. The "Live
Preview" tab no longer exists, and instead has been replaced with a
button placed next to the document controls (subject to change).

Before:


https://github.com/user-attachments/assets/48518b02-87ba-4750-ba7b-b21b5c75240a

After:


https://github.com/user-attachments/assets/a8ec8657-a6d6-4ee1-b9a7-3c1173bcfa96

Author: jacobsfletch

docs/custom-components/document-views.mdx

@@ -30,7 +30,6 @@ export const MyCollectionOrGlobalConfig: CollectionConfig = {
           // - api
           // - versions
           // - version
-          // - livePreview
           // - [key: string]
           // See below for more details
         },

packages/next/src/elements/DocumentHeader/Tabs/tabs/index.tsx

@@ -28,32 +28,6 @@ export const getTabs = ({
       },
       viewPath: '/',
     },
-    {
-      tab: {
-        condition: ({ collectionConfig, config, globalConfig }) => {
-          if (collectionConfig) {
-            return Boolean(
-              config?.admin?.livePreview?.collections?.includes(collectionConfig.slug) ||
-                collectionConfig?.admin?.livePreview,
-            )
-          }
-
-          if (globalConfig) {
-            return Boolean(
-              config?.admin?.livePreview?.globals?.includes(globalConfig.slug) ||
-                globalConfig?.admin?.livePreview,
-            )
-          }
-
-          return false
-        },
-        href: '/preview',
-        label: ({ t }) => t('general:livePreview'),
-        order: 200,
-        ...(customViews?.['livePreview']?.tab || {}),
-      },
-      viewPath: '/preview',
-    },
     {
       tab: {
         condition: ({ collectionConfig, globalConfig, permissions }) =>

packages/next/src/views/Document/getDocumentView.tsx

@@ -12,7 +12,6 @@ import type { ViewToRender } from './index.js'
 
 import { APIView as DefaultAPIView } from '../API/index.js'
 import { EditView as DefaultEditView } from '../Edit/index.js'
-import { LivePreviewView as DefaultLivePreviewView } from '../LivePreview/index.js'
 import { UnauthorizedViewWithGutter } from '../Unauthorized/index.js'
 import { VersionView as DefaultVersionView } from '../Version/index.js'
 import { VersionsView as DefaultVersionsView } from '../Versions/index.js'
@@ -112,7 +111,6 @@ export const getDocumentView = ({
       }
 
       // --> /collections/:collectionSlug/:id/api
-      // --> /collections/:collectionSlug/:id/preview
       // --> /collections/:collectionSlug/:id/versions
       // --> /collections/:collectionSlug/:id/<custom-segment>
       case 4: {
@@ -125,17 +123,6 @@ export const getDocumentView = ({
             break
           }
 
-          case 'preview': {
-            // --> /collections/:collectionSlug/:id/preview
-            if (
-              (collectionConfig && collectionConfig?.admin?.livePreview) ||
-              config?.admin?.livePreview?.collections?.includes(collectionConfig?.slug)
-            ) {
-              View = getCustomViewByKey(views, 'livePreview') || DefaultLivePreviewView
-            }
-            break
-          }
-
           case 'versions': {
             // --> /collections/:collectionSlug/:id/versions
             if (docPermissions?.readVersions) {
@@ -234,7 +221,6 @@ export const getDocumentView = ({
 
       case 3: {
         // --> /globals/:globalSlug/api
-        // --> /globals/:globalSlug/preview
         // --> /globals/:globalSlug/versions
         // --> /globals/:globalSlug/<custom-segment>
         switch (segment3) {
@@ -247,18 +233,6 @@ export const getDocumentView = ({
             break
           }
 
-          case 'preview': {
-            // --> /globals/:globalSlug/preview
-            if (
-              (globalConfig && globalConfig?.admin?.livePreview) ||
-              config?.admin?.livePreview?.globals?.includes(globalConfig?.slug)
-            ) {
-              View = getCustomViewByKey(views, 'livePreview') || DefaultLivePreviewView
-            }
-
-            break
-          }
-
           case 'versions': {
             // --> /globals/:globalSlug/versions
             if (docPermissions?.readVersions) {

packages/next/src/views/Document/getMetaBySegment.tsx

@@ -6,7 +6,6 @@ import type { GenerateViewMetadata } from '../Root/index.js'
 import { getNextRequestI18n } from '../../utilities/getNextRequestI18n.js'
 import { generateAPIViewMetadata } from '../API/metadata.js'
 import { generateEditViewMetadata } from '../Edit/metadata.js'
-import { generateLivePreviewViewMetadata } from '../LivePreview/metadata.js'
 import { generateNotFoundViewMetadata } from '../NotFound/metadata.js'
 import { generateVersionViewMetadata } from '../Version/metadata.js'
 import { generateVersionsViewMetadata } from '../Versions/metadata.js'
@@ -50,10 +49,6 @@ export const getMetaBySegment: GenerateEditViewMetadata = async ({
           // `/:collection/:id/api`
           fn = generateAPIViewMetadata
           break
-        case 'preview':
-          // `/:collection/:id/preview`
-          fn = generateLivePreviewViewMetadata
-          break
         case 'versions':
           // `/:collection/:id/versions`
           fn = generateVersionsViewMetadata
@@ -89,10 +84,6 @@ export const getMetaBySegment: GenerateEditViewMetadata = async ({
           // `/:global/api`
           fn = generateAPIViewMetadata
           break
-        case 'preview':
-          // `/:global/preview`
-          fn = generateLivePreviewViewMetadata
-          break
         case 'versions':
           // `/:global/versions`
           fn = generateVersionsViewMetadata

packages/next/src/views/Document/index.tsx

@@ -1,5 +1,6 @@
 import type {
   AdminViewServerProps,
+  CollectionPreferences,
   Data,
   DocumentViewClientProps,
   DocumentViewServerProps,
@@ -9,7 +10,12 @@ import type {
   RenderDocumentVersionsProperties,
 } from 'payload'
 
-import { DocumentInfoProvider, EditDepthProvider, HydrateAuthProvider } from '@payloadcms/ui'
+import {
+  DocumentInfoProvider,
+  EditDepthProvider,
+  HydrateAuthProvider,
+  LivePreviewProvider,
+} from '@payloadcms/ui'
 import { RenderServerComponent } from '@payloadcms/ui/elements/RenderServerComponent'
 import { isEditing as getIsEditing } from '@payloadcms/ui/shared'
 import { buildFormState } from '@payloadcms/ui/utilities/buildFormState'
@@ -21,6 +27,7 @@ import React from 'react'
 import type { GenerateEditViewMetadata } from './getMetaBySegment.js'
 
 import { DocumentHeader } from '../../elements/DocumentHeader/index.js'
+import { getPreferences } from '../../utilities/getPreferences.js'
 import { NotFoundView } from '../NotFound/index.js'
 import { getDocPreferences } from './getDocPreferences.js'
 import { getDocumentData } from './getDocumentData.js'
@@ -84,6 +91,7 @@ export const renderDocument = async ({
       payload: {
         config,
         config: {
+          admin: { livePreview: livePreviewConfig },
           routes: { admin: adminRoute, api: apiRoute },
           serverURL,
         },
@@ -119,6 +127,7 @@ export const renderDocument = async ({
     docPreferences,
     { docPermissions, hasPublishPermission, hasSavePermission },
     { currentEditor, isLocked, lastUpdateTime },
+    entityPreferences,
   ] = await Promise.all([
     // Get document preferences
     getDocPreferences({
@@ -146,8 +155,18 @@ export const renderDocument = async ({
       isEditing,
       req,
     }),
+
+    // get entity preferences
+    getPreferences<CollectionPreferences>(
+      collectionSlug ? `collection-${collectionSlug}` : `global-${globalSlug}`,
+      payload,
+      req.user.id,
+      req.user.collection,
+    ),
   ])
 
+  const operation = (collectionSlug && idFromArgs) || globalSlug ? 'update' : 'create'
+
   const [
     { hasPublishedDoc, mostRecentVersionIsAutosaved, unpublishedVersionCount, versionCount },
     { state: formState },
@@ -171,7 +190,7 @@ export const renderDocument = async ({
       fallbackLocale: false,
       globalSlug,
       locale: locale?.code,
-      operation: (collectionSlug && idFromArgs) || globalSlug ? 'update' : 'create',
+      operation,
       renderAllFields: true,
       req,
       schemaPath: collectionSlug || globalSlug,
@@ -310,6 +329,22 @@ export const renderDocument = async ({
     viewType,
   }
 
+  const livePreviewURL =
+    typeof livePreviewConfig?.url === 'function'
+      ? await livePreviewConfig.url({
+          collectionConfig,
+          data: doc,
+          globalConfig,
+          locale,
+          req,
+          /**
+           * @deprecated
+           * Use `req.payload` instead. This will be removed in the next major version.
+           */
+          payload: initPageResult.req.payload,
+        })
+      : livePreviewConfig?.url
+
   return {
     data: doc,
     Document: (
@@ -337,24 +372,31 @@ export const renderDocument = async ({
         unpublishedVersionCount={unpublishedVersionCount}
         versionCount={versionCount}
       >
-        {showHeader && !drawerSlug && (
-          <DocumentHeader
-            collectionConfig={collectionConfig}
-            globalConfig={globalConfig}
-            i18n={i18n}
-            payload={payload}
-            permissions={permissions}
-          />
-        )}
-        <HydrateAuthProvider permissions={permissions} />
-        <EditDepthProvider>
-          {RenderServerComponent({
-            clientProps,
-            Component: View,
-            importMap,
-            serverProps: documentViewServerProps,
-          })}
-        </EditDepthProvider>
+        <LivePreviewProvider
+          breakpoints={livePreviewConfig?.breakpoints}
+          isLivePreviewing={entityPreferences?.value?.editViewType === 'live-preview'}
+          operation={operation}
+          url={livePreviewURL}
+        >
+          {showHeader && !drawerSlug && (
+            <DocumentHeader
+              collectionConfig={collectionConfig}
+              globalConfig={globalConfig}
+              i18n={i18n}
+              payload={payload}
+              permissions={permissions}
+            />
+          )}
+          <HydrateAuthProvider permissions={permissions} />
+          <EditDepthProvider>
+            {RenderServerComponent({
+              clientProps,
+              Component: View,
+              importMap,
+              serverProps: documentViewServerProps,
+            })}
+          </EditDepthProvider>
+        </LivePreviewProvider>
       </DocumentInfoProvider>
     ),
   }