feat(nuxt): custom enable/disable hooks for `usePreviewMode` (#28371)

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.

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()