feat: route transitions (#9275)

Due to nature of server-side rendering, navigation within the admin
panel can lead to slow page response times. This can lead to the feeling
of an unresponsive app after clicking a link, for example, where the
page remains in a stale state while the server is processing. This is
especially noticeable on slow networks when navigating to data heavy or
process intensive pages.

To alleviate the bad UX that this causes, the user needs immediate
visual indication that _something_ is taking place. This PR renders a
progress bar in the admin panel which is immediately displayed when a
user clicks a link, and incrementally grows in size until the new route
has loaded in.

Inspired by https://github.com/vercel/react-transition-progress.

Old:

https://github.com/user-attachments/assets/1820dad1-3aea-417f-a61d-52244b12dc8d

New:

https://github.com/user-attachments/assets/99f4bb82-61d9-4a4c-9bdf-9e379bbafd31

To tie into the progress bar, you'll need to use Payload's new `Link`
component instead of the one provided by Next.js:

```diff
- import { Link } from 'next/link'
+ import { Link } from '@payloadcms/ui'
```

Here's an example:

```tsx
import { Link } from '@payloadcms/ui'

const MyComponent = () => {
  return (
    <Link href="/somewhere">
      Go Somewhere
    </Link>
  )
}
```

In order to trigger route transitions for a direct router event such as
`router.push`, you'll need to wrap your function calls with the
`startRouteTransition` method provided by the `useRouteTransition` hook.

```ts
'use client'
import React, { useCallback } from 'react'
import { useTransition } from '@payloadcms/ui'
import { useRouter } from 'next/navigation'

const MyComponent: React.FC = () => {
  const router = useRouter()
  const { startRouteTransition } = useRouteTransition()
 
  const redirectSomewhere = useCallback(() => {
    startRouteTransition(() => router.push('/somewhere'))
  }, [startRouteTransition, router])
 
  // ...
}
```

In the future [Next.js might provide native support for
this](vercel/next.js#41934 (comment)),
and if it does, this implementation can likely be simplified.

Of course there are other ways of achieving this, such as with
[Suspense](https://react.dev/reference/react/Suspense), but they all
come with a different set of caveats. For example with Suspense, you
must provide a fallback component. This means that the user might be
able to immediately navigate to the new page, which is good, but they'd
be presented with a skeleton UI while the other parts of the page stream
in. Not necessarily an improvement to UX as there would be multiple
loading states with this approach.

There are other problems with using Suspense as well. Our default
template, for example, contains the app header and sidebar which are not
rendered within the root layout. This means that they need to stream in
every single time. On fast networks, this would also lead to a
noticeable "blink" unless there is some mechanism by which we can detect
and defer the fallback from ever rendering in such cases. Might still be
worth exploring in the future though.

Author: jacobsfletch

docs/admin/hooks.mdx

@@ -1113,5 +1113,40 @@ setParams({ depth: 2 })
 
 This is useful for scenarios where you need to trigger another fetch regardless of the `url` argument changing.
 
+## useRouteTransition
 
+Route transitions are useful in showing immediate visual feedback to the user when navigating between pages. This is especially useful on slow networks when navigating to data heavy or process intensive pages.
 
+By default, any instances of `Link` from `@payloadcms/ui` will trigger route transitions dy default.
+
+```tsx
+import { Link } from '@payloadcms/ui'
+
+const MyComponent = () => {
+  return (
+    <Link href="/somewhere">
+      Go Somewhere
+    </Link>
+  )
+}
+```
+
+You can also trigger route transitions programmatically, such as when using `router.push` from `next/router`. To do this, wrap your function calls with the `startRouteTransition` method provided by the `useRouteTransition` hook.
+
+```ts
+'use client'
+import React, { useCallback } from 'react'
+import { useTransition } from '@payloadcms/ui'
+import { useRouter } from 'next/navigation'
+
+const MyComponent: React.FC = () => {
+  const router = useRouter()
+  const { startRouteTransition } = useRouteTransition()
+
+  const redirectSomewhere = useCallback(() => {
+    startRouteTransition(() => router.push('/somewhere'))
+  }, [startRouteTransition, router])
+
+  // ...
+}
+```

packages/next/src/elements/DocumentHeader/Tabs/Tab/TabLink.tsx

@@ -1,13 +1,11 @@
 'use client'
 import type { SanitizedConfig } from 'payload'
 
+import { Link } from '@payloadcms/ui'
 import { formatAdminURL } from '@payloadcms/ui/shared'
-import LinkImport from 'next/link.js'
 import { useParams, usePathname, useSearchParams } from 'next/navigation.js'
 import React from 'react'
 
-const Link = (LinkImport.default || LinkImport) as unknown as typeof LinkImport.default
-
 export const DocumentTabLink: React.FC<{
   adminRoute: SanitizedConfig['routes']['admin']
   ariaLabel?: string

packages/next/src/elements/Nav/index.client.tsx

@@ -4,9 +4,8 @@ import type { groupNavItems } from '@payloadcms/ui/shared'
 import type { NavPreferences } from 'payload'
 
 import { getTranslation } from '@payloadcms/translations'
-import { NavGroup, useConfig, useTranslation } from '@payloadcms/ui'
+import { Link, NavGroup, useConfig, useTranslation } from '@payloadcms/ui'
 import { EntityType, formatAdminURL } from '@payloadcms/ui/shared'
-import LinkWithDefault from 'next/link.js'
 import { usePathname } from 'next/navigation.js'
 import React, { Fragment } from 'react'
 
@@ -45,9 +44,6 @@ export const DefaultNavClient: React.FC<{
                 id = `nav-global-${slug}`
               }
 
-              const Link = (LinkWithDefault.default ||
-                LinkWithDefault) as typeof LinkWithDefault.default
-
               const LinkElement = Link || 'a'
               const activeCollection =
                 pathname.startsWith(href) && ['/', undefined].includes(pathname[href.length])

packages/next/src/elements/Nav/index.tsx

@@ -1,14 +1,14 @@
 import type { EntityToGroup } from '@payloadcms/ui/shared'
 import type { ServerProps } from 'payload'
 
-import { Logout } from '@payloadcms/ui'
+import { Link, Logout } from '@payloadcms/ui'
 import { RenderServerComponent } from '@payloadcms/ui/elements/RenderServerComponent'
 import { EntityType, groupNavItems } from '@payloadcms/ui/shared'
 import React from 'react'
 
-import './index.scss'
 import { NavHamburger } from './NavHamburger/index.js'
 import { NavWrapper } from './NavWrapper/index.js'
+import './index.scss'
 
 const baseClass = 'nav'
 
@@ -73,6 +73,7 @@ export const DefaultNav: React.FC<NavProps> = async (props) => {
   const LogoutComponent = RenderServerComponent({
     clientProps: {
       documentSubViewType,
+      Link,
       viewType,
     },
     Component: logout?.Button,

packages/next/src/layouts/Root/index.tsx

@@ -2,7 +2,7 @@ import type { AcceptedLanguages } from '@payloadcms/translations'
 import type { ImportMap, LanguageOptions, SanitizedConfig, ServerFunctionClient } from 'payload'
 
 import { rtlLanguages } from '@payloadcms/translations'
-import { RootProvider } from '@payloadcms/ui'
+import { ProgressBar, RootProvider } from '@payloadcms/ui'
 import { getClientConfig } from '@payloadcms/ui/utilities/getClientConfig'
 import { headers as getHeaders, cookies as nextCookies } from 'next/headers.js'
 import { getPayload, getRequestLanguage, parseCookies } from 'payload'
@@ -135,6 +135,7 @@ export const RootLayout = async ({
           translations={req.i18n.translations}
           user={req.user}
         >
+          <ProgressBar />
           {Array.isArray(config.admin?.components?.providers) &&
           config.admin?.components?.providers.length > 0 ? (
             <NestProviders

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

@@ -1,18 +1,15 @@
 import type { EntityToGroup } from '@payloadcms/ui/shared'
 import type { AdminViewProps } from 'payload'
 
-import { HydrateAuthProvider, SetStepNav } from '@payloadcms/ui'
+import { HydrateAuthProvider, Link, SetStepNav } from '@payloadcms/ui'
 import { RenderServerComponent } from '@payloadcms/ui/elements/RenderServerComponent'
 import { EntityType, groupNavItems } from '@payloadcms/ui/shared'
-import LinkImport from 'next/link.js'
 import React, { Fragment } from 'react'
 
 import { DefaultDashboard } from './Default/index.js'
 
 export { generateDashboardMetadata } from './meta.js'
 
-const Link = (LinkImport.default || LinkImport) as unknown as typeof LinkImport.default
-
 export const Dashboard: React.FC<AdminViewProps> = async ({
   initPageResult,
   params,
@@ -119,7 +116,6 @@ export const Dashboard: React.FC<AdminViewProps> = async ({
         serverProps: {
           globalData,
           i18n,
-          Link,
           locale,
           navGroups,
           params,

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

@@ -1,16 +1,14 @@
 import type { AdminViewProps } from 'payload'
 
-import { Button } from '@payloadcms/ui'
+import { Button, Link } from '@payloadcms/ui'
 import { formatAdminURL, Translation } from '@payloadcms/ui/shared'
-import LinkImport from 'next/link.js'
 import React, { Fragment } from 'react'
 
 import { FormHeader } from '../../elements/FormHeader/index.js'
 import { ForgotPasswordForm } from './ForgotPasswordForm/index.js'
 
 export { generateForgotPasswordMetadata } from './meta.js'
 
-const Link = (LinkImport.default || LinkImport) as unknown as typeof LinkImport.default
 export const forgotPasswordBaseClass = 'forgot-password'
 
 export const ForgotPasswordView: React.FC<AdminViewProps> = ({ initPageResult }) => {

packages/next/src/views/LivePreview/index.client.tsx

@@ -28,6 +28,7 @@ import {
   useDocumentEvents,
   useDocumentInfo,
   useEditDepth,
+  useRouteTransition,
   useServerFunctions,
   useTranslation,
   useUploadEdits,
@@ -131,6 +132,7 @@ const PreviewView: React.FC<Props> = ({
   const { reportUpdate } = useDocumentEvents()
   const { resetUploadEdits } = useUploadEdits()
   const { getFormState } = useServerFunctions()
+  const { startRouteTransition } = useRouteTransition()
 
   const docConfig = collectionConfig || globalConfig
 
@@ -211,7 +213,8 @@ const PreviewView: React.FC<Props> = ({
           adminRoute,
           path: `/collections/${collectionSlug}/${json?.doc?.id}${locale ? `?locale=${locale}` : ''}`,
         })
-        router.push(redirectRoute)
+
+        startRouteTransition(() => router.push(redirectRoute))
       } else {
         resetUploadEdits()
       }
@@ -269,6 +272,7 @@ const PreviewView: React.FC<Props> = ({
       router,
       setDocumentIsLocked,
       updateSavedDocumentData,
+      startRouteTransition,
       user,
       userSlug,
       autosaveEnabled,

packages/next/src/views/Login/LoginForm/index.tsx

@@ -1,15 +1,21 @@
 'use client'
 
-import LinkImport from 'next/link.js'
 import React from 'react'
 
 const baseClass = 'login__form'
-const Link = (LinkImport.default || LinkImport) as unknown as typeof LinkImport.default
 
 import type { UserWithToken } from '@payloadcms/ui'
 import type { FormState } from 'payload'
 
-import { Form, FormSubmit, PasswordField, useAuth, useConfig, useTranslation } from '@payloadcms/ui'
+import {
+  Form,
+  FormSubmit,
+  Link,
+  PasswordField,
+  useAuth,
+  useConfig,
+  useTranslation,
+} from '@payloadcms/ui'
 import { formatAdminURL } from '@payloadcms/ui/shared'
 import { getLoginOptions } from 'payload/shared'
 

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

@@ -5,8 +5,8 @@ import { redirect } from 'next/navigation.js'
 import React, { Fragment } from 'react'
 
 import { Logo } from '../../elements/Logo/index.js'
-import './index.scss'
 import { LoginForm } from './LoginForm/index.js'
+import './index.scss'
 
 export { generateLoginMetadata } from './meta.js'