From 0a6e5e1caae10482c1e5c83196303e878b2967b8 Mon Sep 17 00:00:00 2001
From: Adam DeHaven <2229946+adamdehaven@users.noreply.github.com>
Date: Thu, 8 Aug 2024 08:52:28 -0400
Subject: [PATCH] feat(nuxt): custom enable/disable hooks for `usePreviewMode`
 (#28371)

---
 docs/3.api/2.composables/use-preview-mode.md | 19 ++++++++++++++
 packages/nuxt/src/app/composables/preview.ts | 27 ++++++++++++++++++--
 2 files changed, 44 insertions(+), 2 deletions(-)

diff --git a/docs/3.api/2.composables/use-preview-mode.md b/docs/3.api/2.composables/use-preview-mode.md
index 34450bc339..fad6179bba 100644
--- a/docs/3.api/2.composables/use-preview-mode.md
+++ b/docs/3.api/2.composables/use-preview-mode.md
@@ -52,6 +52,25 @@ const { enabled, state } = usePreviewMode({
 The `getState` function will append returned values to current state, so be careful not to accidentally overwrite important state.
 ::
 
+### Customize the `onEnable` and `onDisable` callbacks
+
+By default, when `usePreviewMode` is enabled, it will call `refreshNuxtData()` to re-fetch all data from the server.
+
+When preview mode is disabled, the composable will attach a callback to call `refreshNuxtData()` to run after a subsequent router navigation.
+
+You can specify custom callbacks to be triggered by providing your own functions for the `onEnable` and `onDisable` options.
+
+```js
+const { enabled, state } = usePreviewMode({
+  onEnable: () => {
+    console.log('preview mode has been enabled')
+  },
+  onDisable: () => {
+    console.log('preview mode has been disabled')
+  }
+})
+```
+
 ## Example
 
 The example below creates a page where part of a content is rendered only in preview mode.
diff --git a/packages/nuxt/src/app/composables/preview.ts b/packages/nuxt/src/app/composables/preview.ts
index 94f8a896d1..18ca6a1d11 100644
--- a/packages/nuxt/src/app/composables/preview.ts
+++ b/packages/nuxt/src/app/composables/preview.ts
@@ -10,9 +10,31 @@ interface Preview {
   _initialized?: boolean
 }
 
+/**
+ * Options for configuring preview mode.
+ */
 interface PreviewModeOptions<S> {
+  /**
+   * A function that determines whether preview mode should be enabled based on the current state.
+   * @param {Record<any, unknown>} state - The state of the preview.
+   * @returns {boolean} A boolean indicating whether the preview mode is enabled.
+   */
   shouldEnable?: (state: Preview['state']) => boolean
+  /**
+   * A function that retrieves the current state.
+   * The `getState` function will append returned values to current state, so be careful not to accidentally overwrite important state.
+   * @param {Record<any, unknown>} state - The preview state.
+   * @returns {Record<any, unknown>} The preview state.
+   */
   getState?: (state: Preview['state']) => S
+  /**
+   * A function to be called when the preview mode is enabled.
+   */
+  onEnable?: () => void
+  /**
+   * A function to be called when the preview mode is disabled.
+   */
+  onDisable?: () => void
 }
 
 type EnteredState = Record<any, unknown> | null | undefined | void
@@ -54,9 +76,10 @@ export function usePreviewMode<S extends EnteredState> (options: PreviewModeOpti
       }
 
       if (import.meta.client && !unregisterRefreshHook) {
-        refreshNuxtData()
+        const onEnable = options.onEnable ?? refreshNuxtData
+        onEnable()
 
-        unregisterRefreshHook = useRouter().afterEach(() => refreshNuxtData())
+        unregisterRefreshHook = options.onDisable ?? useRouter().afterEach(() => refreshNuxtData())
       }
     } else if (unregisterRefreshHook) {
       unregisterRefreshHook()