feat: pageContext.pageContextNavigation (#2002)

docs/pages/pageContext/+Page.mdx

@@ -100,6 +100,7 @@ Built-in properties:
  - **`pageContext.config`**: See <Link href="/meta" />.
  - **`pageContext.isHydration`**: Whether the page is rendered to HTML. When using <Link href="/client-routing" noBreadcrumb={true} />, the value is `true` for the first page the user navigates to, and `false` for any subsequent navigation. (When using <Link href="/server-routing" noBreadcrumb={true} />, the value is always `true`.) (If the page doesn't throw an error then it's equivalent to `!pageContext.isClientSideNavigation`, otherwise the error page is rendered and thus `pageContext.isHydration` is `false` whereas `!pageContext.isClientSideNavigation` is `true`.)
  - **`pageContext.isBackwardNavigation`**: Whether the user is navigating back in history. The value is `true` when the user clicks on his browser's backward navigation button, or when invoking `history.back()`. The `isBackwardNavigation` property only works with Client Routing. (The value is always `null` when using Server Routing.)
+ - **`pageContext.previousPageContext`**: Upon client-side page navigation, you can use `pageContext.previousPageContext` to access the `pageContext` of the previous page. See <Link href="#lifecycle" />.
  - **`pageContext.is404`**: If an error occurs, whether the error is a `404 Page Not Found` or a `500 Internal Error`, see <Link href="/error-page" />.
  - **`pageContext.isClientSideNavigation`**: Whether the page was navigated by the client-side router. In other words, when using <Link href="/client-routing" noBreadcrumb={true} />, the value is `false` for the first page the user visits, and `true` for any subsequent navigation. (When using <Link href="/server-routing" noBreadcrumb={true} />, the value is always `false`.)
  - **`pageContext.abortReason`**: Set by <Link href="/render" text={<code>throw render()</code>} /> and used by the <Link text="error page" href="/error-page" />.

vike/client/client-routing-runtime/renderPageClientSide.ts

@@ -60,14 +60,15 @@ const globalObject = getGlobalObject<{
   onRenderClientPromise?: Promise<unknown>
   isFirstRenderDone?: true
   isTransitioning?: true
-  previousPageContext?: PreviousPageContext
+  previousPageContext: PreviousPageContext | null
   firstRenderStartPromise: Promise<void>
   firstRenderStartPromiseResolve: () => void
 }>(
   'renderPageClientSide.ts',
   (() => {
     const { promise: firstRenderStartPromise, resolve: firstRenderStartPromiseResolve } = genPromise()
     return {
+      previousPageContext: null,
       renderCounter: 0,
       firstRenderStartPromise,
       firstRenderStartPromiseResolve
@@ -294,10 +295,22 @@ async function renderPageClientSide(renderArgs: RenderArgs): Promise<void> {
       isBackwardNavigation,
       isClientSideNavigation,
       isHydration: isFirstRender && !isForErrorPage,
-      // Make it public as `pageContext.previousPageContext`/`pageContext.previous`? Maybe after https://github.com/vikejs/vike/issues/1268
-      _previousPageContext: previousPageContext,
+      previousPageContext,
       ...pageContextInitClient
     })
+
+    // TODO/next-major-release: remove
+    Object.defineProperty(pageContext, '_previousPageContext', {
+      get() {
+        assertWarning(false, 'pageContext._previousPageContext has been renamed pageContext.previousPageContext', {
+          showStackTrace: true,
+          onlyOnce: true
+        })
+        return previousPageContext
+      },
+      enumerable: false
+    })
+
     {
       const pageContextFromAllRewrites = getPageContextFromAllRewrites(pageContextsFromRewrite)
       assert(!('urlOriginal' in pageContextFromAllRewrites))

vike/shared/types.ts

@@ -175,6 +175,12 @@ type PageContextBuiltInClientWithClientRouting<Data> = Partial<PageContextBuiltI
      * The value is `true` when the user clicks on his browser's backward navigation button, or when invoking `history.back()`.
      */
     isBackwardNavigation: boolean | null
+    /**
+     * Upon client-side page navigation, you can use `pageContext.previousPageContext` to access the `pageContext` of the previous page.
+     *
+     * https://vike.dev/pageContext
+     */
+    previousPageContext: PageContextClient | null
   } & PageContextUrlClient
 
 type PageContextBuiltInClientWithServerRouting<Data> = Partial<PageContextBuiltInCommon<Data>> &