feat: add global 'beforepopstate' bus to intercept browser back/forward navigation (#509)

src/providers/services/provider.tsx

@@ -0,0 +1,25 @@
+import React, { ReactNode } from "react";
+import { usePopStateBus } from "../../services/beforePopState/usePopStateBus";
+import { WasPopProvider } from "../services/wasPop/provider";
+
+/**
+ * ServicesProvider is a component that initializes and provides access to various service-related
+ * functionality throughout the application.
+ *
+ * This provider:
+ * 1. Registers the pop state bus to handle browser navigation events.
+ * 2. Provides the WasPopProvider context to track browser back/forward navigation
+ *
+ * This provider should be placed at the _app root level to ensure all components have access to these services.
+ */
+
+export function ServicesProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  // Register the pop state bus.
+  usePopStateBus();
+
+  return <WasPopProvider>{children}</WasPopProvider>;
+}

src/providers/services/wasPop/context.ts

@@ -0,0 +1,7 @@
+import { createContext } from "react";
+import { WasPopContextProps } from "./types";
+
+export const WasPopContext = createContext<WasPopContextProps>({
+  onClearPopRef: () => {},
+  popRef: { current: undefined },
+});

src/providers/services/wasPop/hook.ts

@@ -0,0 +1,7 @@
+import { useContext } from "react";
+import { WasPopContext } from "./context";
+import { WasPopContextProps } from "./types";
+
+export const useWasPop = (): WasPopContextProps => {
+  return useContext(WasPopContext);
+};

src/providers/services/wasPop/provider.tsx

@@ -0,0 +1,45 @@
+import React, { ReactNode, useCallback, useRef } from "react";
+import { NextHistoryState } from "../../../services/beforePopState/types";
+import { useOnPopState } from "../../../services/beforePopState/useOnPopState";
+import { WasPopContext } from "./context";
+
+/**
+ * WasPopProvider tracks browser navigation events to determine if the current route change
+ * was triggered by a popstate event (browser back/forward navigation).
+ *
+ * This provider:
+ * 1. Registers callbacks for route change events.
+ * 2. Tracks when navigation occurs via browser back/forward buttons
+ * 3. Provides this state via context to child components
+ *
+ * This allows components to respond differently to user-initiated navigation versus
+ * browser history navigation.
+ */
+
+export function WasPopProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const popRef = useRef<NextHistoryState | undefined>();
+
+  // Pop callback.
+  const onBeforePopState = useCallback((state: NextHistoryState) => {
+    popRef.current = state;
+    return true;
+  }, []);
+
+  // Clear pop ref.
+  const onClearPopRef = useCallback(() => {
+    popRef.current = undefined;
+  }, []);
+
+  // Register the callback to be invoked before pop.
+  useOnPopState(onBeforePopState);
+
+  return (
+    <WasPopContext.Provider value={{ onClearPopRef, popRef }}>
+      {children}
+    </WasPopContext.Provider>
+  );
+}

src/providers/services/wasPop/types.ts

@@ -0,0 +1,7 @@
+import { MutableRefObject } from "react";
+import { NextHistoryState } from "../../../services/beforePopState/types";
+
+export interface WasPopContextProps {
+  onClearPopRef: () => void;
+  popRef: MutableRefObject<NextHistoryState | undefined>;
+}

src/services/beforePopState/popStateBus.ts

@@ -0,0 +1,64 @@
+import Router from "next/router";
+import { BeforePopStateCallback, NextHistoryState } from "./types";
+
+/**
+ * Pop‐State Event Bus
+ *
+ * Provides a centralized mechanism for components to intercept
+ * and optionally prevent Back/Forward navigation (Next.js beforePopState).
+ */
+
+/**
+ * A set of callback functions that will run before Next.js performs a pop.
+ * Each callback returns `true` to allow navigation or `false` to block.
+ */
+const beforePopCallbacks = new Set<BeforePopStateCallback>();
+
+/**
+ * Register a callback to be invoked immediately before any Next.js pop navigation.
+ * Return `false` from your callback to prevent the pop; otherwise return `true`.
+ * @param cb - The callback function to register.
+ */
+export function registerBeforePopCallback(cb: BeforePopStateCallback): void {
+  beforePopCallbacks.add(cb);
+}
+
+/**
+ * Unregister a previously registered “before pop” callback.
+ * @param cb - The callback function to unregister.
+ */
+export function unregisterBeforePopCallback(cb: BeforePopStateCallback): void {
+  beforePopCallbacks.delete(cb);
+}
+
+/**
+ * Ensures that we only hook into Next.js once. After install, any pop event
+ * will first invoke all registered callbacks and only proceed if all return true.
+ */
+let hasInstalledInterceptor = false;
+
+/**
+ * Install the global “before pop” interceptor into Next.js’s router.
+ * Subsequent calls to this function will be no‐ops.
+ *
+ * This method must be called once (e.g. in your app’s top‐level code)
+ * to enable the pop‐state bus.
+ */
+export function registerPopStateHandler(): void {
+  if (hasInstalledInterceptor) return;
+  hasInstalledInterceptor = true;
+
+  Router.beforePopState((state: NextHistoryState) => {
+    // Iteratively call every callback. If any returns false, block navigation.
+    let allAllow = true;
+    beforePopCallbacks.forEach((cb) => {
+      try {
+        if (cb(state) === false) allAllow = false;
+      } catch (e: unknown) {
+        console.error("Pop listener failed:", e);
+      }
+    });
+
+    return allAllow;
+  });
+}

src/services/beforePopState/types.ts

@@ -0,0 +1,15 @@
+import Router from "next/router";
+
+/**
+ * Type representing the callback function passed to beforePopState.
+ * Extracted from the Next.js Router.beforePopState API.
+ */
+export type BeforePopStateCallback = Parameters<
+  typeof Router.beforePopState
+>[0];
+
+/**
+ * Type representing the state passed to beforePopState.
+ * Extracted from the Next.js Router.beforePopState API.
+ */
+export type NextHistoryState = Parameters<BeforePopStateCallback>[0];

src/services/beforePopState/useOnPopState.ts

@@ -0,0 +1,15 @@
+import { useEffect } from "react";
+import {
+  registerBeforePopCallback,
+  unregisterBeforePopCallback,
+} from "./popStateBus";
+import { BeforePopStateCallback } from "./types";
+
+export const useOnPopState = (cb: BeforePopStateCallback): void => {
+  useEffect(() => {
+    registerBeforePopCallback(cb);
+    return (): void => {
+      unregisterBeforePopCallback(cb);
+    };
+  }, [cb]);
+};

src/services/beforePopState/usePopStateBus.ts

@@ -0,0 +1,14 @@
+import { useEffect } from "react";
+import { registerPopStateHandler } from "./popStateBus";
+
+/**
+ * Registers the single global `router.beforePopState` handler that
+ * fans out to all feature listeners.
+ * Safe to call multiple times - only the first invocation does the real install.
+ */
+
+export const usePopStateBus = (): void => {
+  useEffect(() => {
+    registerPopStateHandler();
+  }, []);
+};