Merge remote-tracking branch 'origin/main' into feat/accurate-lexical-types

Author: AlessioGr

docs/migration-guide/v4.mdx

@@ -151,6 +151,60 @@ Several types and utilities that were re-exported from `@payloadcms/ui` and `@pa
 
 Run `npx @payloadcms/codemod --transform migrate-aliased-exports` to migrate automatically. Renamed types are imported using an `as` alias (e.g. `import type { CollectionPreferences as ListPreferences } from 'payload'`) so existing usages keep compiling — drop the alias and rename usages manually if you want to fully commit to the new name.
 
+### `next/navigation` and `next/link` replaced by framework-agnostic `RouterAdapter` hooks
+
+`@payloadcms/ui` no longer depends on `next` directly. Custom admin components (field components, custom views, plugins) that previously imported router hooks or the `Link` component from `next/*` must now import the framework-agnostic equivalents from `@payloadcms/ui`. Behavior is identical when running on Next.js — the `NextRouterAdapter` shipped by `@payloadcms/next` wires `next/navigation` hooks and `next/link` into the same context — but ui code can now also run on non-Next adapters (e.g. TanStack Start) without modification.
+
+**Hooks** — import from `@payloadcms/ui` instead of `next/navigation`:
+
+| Old import                                          | New import                                         |
+| --------------------------------------------------- | -------------------------------------------------- |
+| `import { useRouter } from 'next/navigation'`       | `import { useRouter } from '@payloadcms/ui'`       |
+| `import { usePathname } from 'next/navigation'`     | `import { usePathname } from '@payloadcms/ui'`     |
+| `import { useSearchParams } from 'next/navigation'` | `import { useSearchParams } from '@payloadcms/ui'` |
+| `import { useParams } from 'next/navigation'`       | `import { useParams } from '@payloadcms/ui'`       |
+
+**`Link` component** — use `PayloadLink` from `@payloadcms/ui`:
+
+```diff
+- import Link from 'next/link'
++ import { PayloadLink as Link } from '@payloadcms/ui'
+```
+
+**Types** — `LinkProps` from `next/link` is replaced by `LinkAdapterProps` from `payload`:
+
+```diff
+- import type { LinkProps } from 'next/link'
++ import type { LinkAdapterProps } from 'payload'
+```
+
+`LinkAdapterProps` is a framework-neutral shape: `href: string`, optional `prefetch` / `replace` / `scroll` / `ref`, plus standard `AnchorHTMLAttributes<HTMLAnchorElement>` (minus `href`). The Next adapter forwards these to `next/link`.
+
+**`RouterAdapterRouter` shape** — the object returned by `useRouter()` now has a stable, framework-agnostic surface:
+
+```ts
+type RouterAdapterRouter = {
+  back: () => void
+  push: (path: string, options?: { scroll?: boolean }) => void
+  refresh: () => void
+  replace: (path: string, options?: { scroll?: boolean }) => void
+}
+```
+
+If you were relying on Next-specific extras like `prefetch()` on the router instance, switch to the `Link` component's `prefetch` prop instead.
+
+**Custom apps embedding `RootProvider`** — `RootProvider` now requires a `RouterAdapter` prop. Apps using the default Next.js admin layout get this wired automatically. If you assemble `RootProvider` yourself, pass the framework's adapter component:
+
+```diff
++ import { NextRouterAdapter } from '@payloadcms/next/elements/RouterAdapter'
+
+  <RootProvider
++   RouterAdapter={NextRouterAdapter}
+    config={clientConfig}
+    /* ... */
+  />
+```
+
 ### `title` and `setDocumentTitle` removed from `useDocumentInfo`
 
 For performance reasons, the document title state has been split out of `DocumentInfoContext` into its own `DocumentTitleContext`. Access it through the `useDocumentTitle` hook, which exposes the same `title` and `setDocumentTitle` API. Components that subscribed to `useDocumentInfo` solely for the title will no longer re-render when unrelated document state changes.

packages/next/src/adapters/router.tsx

@@ -0,0 +1,74 @@
+'use client'
+import type { RouterAdapterContextValue } from '@payloadcms/ui'
+import type { LinkAdapterProps } from 'payload'
+
+import { RouterAdapterContext } from '@payloadcms/ui'
+import NextLinkImport from 'next/link.js'
+import {
+  useParams as useNextParams,
+  usePathname as useNextPathname,
+  useRouter as useNextRouter,
+  useSearchParams as useNextSearchParams,
+} from 'next/navigation.js'
+import React from 'react'
+
+type LinkComponent = React.FC<
+  {
+    children?: React.ReactNode
+    href: string
+    prefetch?: boolean
+    ref?: React.Ref<HTMLAnchorElement>
+    replace?: boolean
+    scroll?: boolean
+  } & Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href'>
+>
+
+const NextLink: LinkComponent = ('default' in NextLinkImport
+  ? NextLinkImport.default
+  : NextLinkImport) as unknown as LinkComponent
+
+const NextLinkAdapter: React.FC<LinkAdapterProps> = ({
+  children,
+  href,
+  prefetch,
+  ref,
+  replace,
+  scroll,
+  ...rest
+}) => {
+  return (
+    <NextLink href={href} prefetch={prefetch} ref={ref} replace={replace} scroll={scroll} {...rest}>
+      {children}
+    </NextLink>
+  )
+}
+
+export const NextRouterAdapter: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const nextRouter = useNextRouter()
+  const pathname = useNextPathname()
+  const searchParams = useNextSearchParams()
+  const params = useNextParams()
+
+  const router = React.useMemo<RouterAdapterContextValue['router']>(
+    () => ({
+      back: nextRouter.back,
+      push: nextRouter.push,
+      refresh: nextRouter.refresh,
+      replace: nextRouter.replace,
+    }),
+    [nextRouter],
+  )
+
+  const value = React.useMemo<RouterAdapterContextValue>(
+    () => ({
+      Link: NextLinkAdapter,
+      params: params as Record<string, string | string[]>,
+      pathname,
+      router,
+      searchParams,
+    }),
+    [params, pathname, router, searchParams],
+  )
+
+  return <RouterAdapterContext value={value}>{children}</RouterAdapterContext>
+}

packages/next/src/adapters/server.ts

@@ -0,0 +1,43 @@
+import type { CookieStore, ServerAdapter } from 'payload'
+
+import { cookies as getNextCookies, headers as getNextHeaders } from 'next/headers.js'
+import {
+  forbidden as nextForbidden,
+  notFound as nextNotFound,
+  permanentRedirect as nextPermanentRedirect,
+  redirect as nextRedirect,
+  unauthorized as nextUnauthorized,
+} from 'next/navigation.js'
+
+const toCookieStore = async (): Promise<CookieStore> => {
+  const store = await getNextCookies()
+
+  return {
+    get: (name) => {
+      const cookie = store.get(name)
+      return cookie ? { name: cookie.name, value: cookie.value } : undefined
+    },
+    getAll: () => store.getAll().map((cookie) => ({ name: cookie.name, value: cookie.value })),
+    set: (name, value, options) => {
+      store.set(name, value, options)
+    },
+  }
+}
+
+/**
+ * Adapts Next.js server-side APIs to the framework-agnostic `ServerAdapter` interface.
+ * This way we can invoke these methods within our server components and plugins without importing Next.js modules directly.
+ */
+export const nextServerAdapter: ServerAdapter = {
+  forbidden: () => nextForbidden(),
+  getCookies: toCookieStore,
+  getHeaders: () => getNextHeaders(),
+  notFound: () => nextNotFound(),
+  permanentRedirect: (path) => nextPermanentRedirect(path),
+  redirect: (path) => nextRedirect(path),
+  setCookie: async (name, value, options) => {
+    const store = await getNextCookies()
+    store.set(name, value, options)
+  },
+  unauthorized: () => nextUnauthorized(),
+}

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

@@ -82,6 +82,7 @@ export const DefaultDocumentTab: React.FC<{
                 payload: req.payload,
                 permissions,
                 req,
+                server: req.server,
                 user: req.user,
               } satisfies DocumentTabServerPropsOnly,
             })}

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

@@ -61,6 +61,7 @@ export const DocumentTabs: React.FC<{
                     payload: req.payload,
                     permissions,
                     req,
+                    server: req.server,
                     user: req.user,
                   } satisfies DocumentTabServerPropsOnly,
                 })

packages/next/src/elements/Nav/NavWrapper/index.scss

@@ -9,19 +9,9 @@
     height: 100vh;
     width: var(--nav-width);
     border-right: 1px solid var(--theme-elevation-100);
-    opacity: 0;
-
     [dir='rtl'] & {
       border-right: none;
       border-left: 1px solid var(--theme-elevation-100);
     }
-
-    &--nav-animate {
-      transition: opacity var(--nav-trans-time) ease-in-out;
-    }
-
-    &--nav-open {
-      opacity: 1;
-    }
   }
 }

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

@@ -13,14 +13,13 @@ export const NavWrapper: React.FC<{
 }> = (props) => {
   const { baseClass, children } = props
 
-  const { hydrated, navOpen, navRef, shouldAnimate } = useNav()
+  const { hydrated, navOpen, navRef } = useNav()
 
   return (
     <aside
       className={[
         baseClass,
         navOpen && `${baseClass}--nav-open`,
-        shouldAnimate && `${baseClass}--nav-animate`,
         hydrated && `${baseClass}--nav-hydrated`,
       ]
         .filter(Boolean)

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

@@ -7,7 +7,6 @@
     height: 100vh;
     width: var(--nav-width);
     border-right: 1px solid var(--color-border);
-    opacity: 0;
     overflow: hidden;
     --nav-padding-inline-start: var(--spacer-2-5);
     --nav-padding-inline-end: var(--spacer-2-5);
@@ -20,14 +19,6 @@
     border-left: 1px solid var(--color-border);
   }
 
-  .nav--nav-animate {
-    transition: opacity var(--nav-trans-time) ease-in-out;
-  }
-
-  .nav--nav-open {
-    opacity: 1;
-  }
-
   .nav__mobile-close {
     display: none;
     background: none;

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

@@ -226,6 +226,7 @@ export const DefaultNav: React.FC<NavProps> = async (props) => {
           permissions={permissions}
           req={req}
           searchParams={searchParams}
+          server={req?.server}
           tabs={allTabs}
           user={user}
           viewType={viewType}

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

@@ -10,6 +10,7 @@ import { cookies as nextCookies } from 'next/headers.js'
 import { applyLocaleFiltering } from 'payload/shared'
 import React, { Suspense } from 'react'
 
+import { NextRouterAdapter } from '../../adapters/router.js'
 import { getNavPrefs } from '../../elements/Nav/getNavPrefs.js'
 import { getRequestHighContrast } from '../../utilities/getRequestHighContrast.js'
 import { getRequestTheme } from '../../utilities/getRequestTheme.js'
@@ -185,6 +186,7 @@ const RootLayoutContent = async ({
           languageOptions={languageOptions}
           locale={req.locale}
           permissions={req.user ? permissions : null}
+          RouterAdapter={NextRouterAdapter}
           serverFunction={serverFunction}
           switchLanguageServerAction={switchLanguageServerAction}
           theme={theme}
@@ -201,6 +203,7 @@ const RootLayoutContent = async ({
                 i18n: req.i18n,
                 payload: req.payload,
                 permissions,
+                server: req.server,
                 user: req.user,
               }}
             >