fix(ui): add support back for custom live preview components (#14037)

Fixes #13308

Adds support for a custom live preview component back, we previously
supported this and it was allowed via the config types but it wasn't
being rendered.

Now we export the `useLivePreviewContext` hook and the original
`LivePreviewWindow` component too so that end users can wrap the live
preview functionality with anything custom that they may need

Author: paulpopus

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

@@ -80,6 +80,18 @@ export const renderDocumentSlots: (args: {
     })
   }
 
+  const LivePreview =
+    collectionConfig?.admin?.components?.views?.edit?.livePreview ||
+    globalConfig?.admin?.components?.views?.edit?.livePreview
+
+  if (LivePreview?.Component) {
+    components.LivePreview = RenderServerComponent({
+      Component: LivePreview.Component,
+      importMap: req.payload.importMap,
+      serverProps,
+    })
+  }
+
   const descriptionFromConfig =
     collectionConfig?.admin?.description || globalConfig?.admin?.description
 

packages/payload/src/admin/types.ts

@@ -561,6 +561,7 @@ export type DocumentSlots = {
   BeforeDocumentControls?: React.ReactNode
   Description?: React.ReactNode
   EditMenuItems?: React.ReactNode
+  LivePreview?: React.ReactNode
   PreviewButton?: React.ReactNode
   PublishButton?: React.ReactNode
   SaveButton?: React.ReactNode

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

@@ -415,3 +415,6 @@ export type {
   RenderFieldServerFnArgs,
   RenderFieldServerFnReturnType,
 } from '../../forms/fieldSchemasToFormState/serverFunctions/renderFieldServerFn.js'
+
+export { useLivePreviewContext } from '../../providers/LivePreview/context.js'
+export { LivePreviewWindow } from '../../elements/LivePreview/Window/index.js'

packages/ui/src/views/Edit/index.tsx

@@ -56,6 +56,7 @@ export function DefaultEditView({
   BeforeDocumentControls,
   Description,
   EditMenuItems,
+  LivePreview: CustomLivePreview,
   PreviewButton,
   PublishButton,
   SaveButton,
@@ -694,7 +695,11 @@ export function DefaultEditView({
               {AfterDocument}
             </div>
             {isLivePreviewEnabled && !isInDrawer && livePreviewURL && (
-              <LivePreviewWindow collectionSlug={collectionSlug} globalSlug={globalSlug} />
+              <>
+                {CustomLivePreview || (
+                  <LivePreviewWindow collectionSlug={collectionSlug} globalSlug={globalSlug} />
+                )}
+              </>
             )}
           </div>
         </Form>

test/live-preview/app/live-preview/(pages)/custom-live-preview/[slug]/RefreshRouteOnSave.tsx

@@ -0,0 +1,12 @@
+'use client'
+
+import { RefreshRouteOnSave as PayloadLivePreview } from '@payloadcms/live-preview-react'
+import { useRouter } from 'next/navigation.js'
+import React from 'react'
+
+import { PAYLOAD_SERVER_URL } from '../../../_api/serverURL.js'
+
+export const RefreshRouteOnSave: React.FC = () => {
+  const router = useRouter()
+  return <PayloadLivePreview refresh={() => router.refresh()} serverURL={PAYLOAD_SERVER_URL} />
+}

test/live-preview/app/live-preview/(pages)/custom-live-preview/[slug]/page.tsx

@@ -0,0 +1,55 @@
+import { Gutter } from '@payloadcms/ui'
+import { notFound } from 'next/navigation.js'
+import React, { Fragment } from 'react'
+
+import type { Page } from '../../../../../payload-types.js'
+
+import { renderedPageTitleID, customLivePreviewSlug } from '../../../../../shared.js'
+import { getDoc } from '../../../_api/getDoc.js'
+import { getDocs } from '../../../_api/getDocs.js'
+import { Blocks } from '../../../_components/Blocks/index.js'
+import { Hero } from '../../../_components/Hero/index.js'
+import { RefreshRouteOnSave } from './RefreshRouteOnSave.js'
+
+type Args = {
+  params: Promise<{
+    slug?: string
+  }>
+}
+
+export default async function SSRAutosavePage({ params: paramsPromise }: Args) {
+  const { slug = '' } = await paramsPromise
+
+  const data = await getDoc<Page>({
+    slug,
+    collection: customLivePreviewSlug,
+    draft: true,
+  })
+
+  if (!data) {
+    notFound()
+  }
+
+  return (
+    <Fragment>
+      <RefreshRouteOnSave />
+      <Hero {...data?.hero} />
+      <Blocks blocks={data?.layout} />
+      <Gutter>
+        <div id={renderedPageTitleID}>{`For Testing: ${data.title}`}</div>
+      </Gutter>
+    </Fragment>
+  )
+}
+
+export async function generateStaticParams() {
+  process.env.PAYLOAD_DROP_DATABASE = 'false'
+  try {
+    const ssrPages = await getDocs<Page>(customLivePreviewSlug)
+    return ssrPages?.map((page) => {
+      return { slug: page.slug }
+    })
+  } catch (_err) {
+    return []
+  }
+}

test/live-preview/collections/CustomLivePreview.ts

@@ -0,0 +1,97 @@
+import type { CollectionConfig } from 'payload'
+
+import { Archive } from '../blocks/ArchiveBlock/index.js'
+import { CallToAction } from '../blocks/CallToAction/index.js'
+import { Content } from '../blocks/Content/index.js'
+import { MediaBlock } from '../blocks/MediaBlock/index.js'
+import { hero } from '../fields/hero.js'
+import { customLivePreviewSlug, mediaSlug, tenantsSlug } from '../shared.js'
+
+export const CustomLivePreview: CollectionConfig = {
+  slug: customLivePreviewSlug,
+  labels: {
+    singular: 'Custom Live Preview Page',
+    plural: 'Custom Live Preview Pages',
+  },
+  access: {
+    read: () => true,
+    create: () => true,
+    update: () => true,
+    delete: () => true,
+  },
+  admin: {
+    useAsTitle: 'title',
+    defaultColumns: ['id', 'title', 'slug', 'createdAt'],
+    preview: (doc) => `/live-preview/ssr/${doc?.slug}`,
+    components: {
+      views: {
+        edit: {
+          livePreview: {
+            Component: '/components/CustomLivePreview.js#CustomLivePreview',
+          },
+        },
+      },
+    },
+  },
+  fields: [
+    {
+      name: 'slug',
+      type: 'text',
+      required: true,
+      admin: {
+        position: 'sidebar',
+      },
+    },
+    {
+      name: 'tenant',
+      type: 'relationship',
+      relationTo: tenantsSlug,
+      admin: {
+        position: 'sidebar',
+      },
+    },
+    {
+      name: 'title',
+      type: 'text',
+      required: true,
+    },
+    {
+      type: 'tabs',
+      tabs: [
+        {
+          label: 'Hero',
+          fields: [hero],
+        },
+        {
+          label: 'Content',
+          fields: [
+            {
+              name: 'layout',
+              type: 'blocks',
+              blocks: [CallToAction, Content, MediaBlock, Archive],
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'meta',
+      type: 'group',
+      fields: [
+        {
+          name: 'title',
+          type: 'text',
+        },
+        {
+          name: 'description',
+          type: 'textarea',
+        },
+        {
+          name: 'image',
+          type: 'upload',
+          relationTo: mediaSlug,
+        },
+      ],
+    },
+  ],
+}

test/live-preview/components/CustomLivePreview.tsx

@@ -0,0 +1,27 @@
+'use client'
+import { LivePreviewWindow, useDocumentInfo, useLivePreviewContext } from '@payloadcms/ui'
+
+import './styles.css'
+
+export function CustomLivePreview() {
+  const { collectionSlug, globalSlug } = useDocumentInfo()
+  const { isLivePreviewing, setURL, url } = useLivePreviewContext()
+
+  return (
+    <div
+      className={[
+        'custom-live-preview',
+        isLivePreviewing && `custom-live-preview--is-live-previewing`,
+      ]
+        .filter(Boolean)
+        .join(' ')}
+    >
+      {isLivePreviewing && (
+        <>
+          <p>Custom live preview being rendered</p>
+          <LivePreviewWindow collectionSlug={collectionSlug} globalSlug={globalSlug} />
+        </>
+      )}
+    </div>
+  )
+}

test/live-preview/components/styles.css

@@ -0,0 +1,13 @@
+.custom-live-preview {
+  width: 80%;
+  display: none;
+  overflow: hidden;
+
+  &.custom-live-preview--is-live-previewing {
+    display: block;
+  }
+
+  .live-preview-window {
+    width: 100%;
+  }
+}

test/live-preview/config.ts

@@ -6,6 +6,7 @@ import { buildConfigWithDefaults } from '../buildConfigWithDefaults.js'
 import { MediaBlock } from './blocks/MediaBlock/index.js'
 import { Categories } from './collections/Categories.js'
 import { CollectionLevelConfig } from './collections/CollectionLevelConfig.js'
+import { CustomLivePreview } from './collections/CustomLivePreview.js'
 import { Media } from './collections/Media.js'
 import { NoURLCollection } from './collections/NoURL.js'
 import { Pages } from './collections/Pages.js'
@@ -19,6 +20,7 @@ import { Footer } from './globals/Footer.js'
 import { Header } from './globals/Header.js'
 import { seed } from './seed/index.js'
 import {
+  customLivePreviewSlug,
   desktopBreakpoint,
   mobileBreakpoint,
   pagesSlug,
@@ -42,7 +44,13 @@ export default buildConfigWithDefaults({
       // The Live Preview config cascades from the top down, properties are inherited from here
       url: formatLivePreviewURL,
       breakpoints: [mobileBreakpoint, desktopBreakpoint],
-      collections: [pagesSlug, postsSlug, ssrPagesSlug, ssrAutosavePagesSlug],
+      collections: [
+        pagesSlug,
+        postsSlug,
+        ssrPagesSlug,
+        ssrAutosavePagesSlug,
+        customLivePreviewSlug,
+      ],
       globals: ['header', 'footer'],
     },
   },
@@ -59,6 +67,7 @@ export default buildConfigWithDefaults({
     Media,
     CollectionLevelConfig,
     StaticURLCollection,
+    CustomLivePreview,
     NoURLCollection,
   ],
   globals: [Header, Footer],