@okyrychenko-dev/react-action-guard-router 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,158 @@
+export { B as BaseNavigationBlockerOptions, a as BeforeUnloadOptions, N as NavigationBlockerReturn } from './types-C3CPuZip.cjs';
+
+/**
+ * Blocks browser tab close/refresh when condition is met.
+ *
+ * This hook adds a `beforeunload` event listener to warn users
+ * before they close or refresh the browser tab. Modern browsers
+ * may ignore custom messages and show their own generic warning.
+ *
+ * @param when - Boolean or function returning boolean to determine if blocking should be active
+ * @param message - Optional custom message (may be ignored by browsers)
+ *
+ * @example
+ * ```tsx
+ * function MyForm() {
+ *   const [hasUnsavedChanges, setHasUnsavedChanges] = useState(false);
+ *
+ *   useBeforeUnload(hasUnsavedChanges, 'You have unsaved changes');
+ *
+ *   return <form>...</form>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With function condition
+ * function EditPage() {
+ *   const isFormDirty = useIsBlocked('form');
+ *
+ *   useBeforeUnload(() => isFormDirty);
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+declare function useBeforeUnload(when: boolean | (() => boolean), message?: string): void;
+
+/**
+ * State object for a confirmation dialog
+ */
+interface DialogState<T = string> {
+    /** Whether the dialog is currently open */
+    isOpen: boolean;
+    /** The data to display in the dialog (typically a message) */
+    message: T;
+    /** Resolver function to confirm/cancel navigation */
+    resolve: (confirmed: boolean) => void;
+}
+/**
+ * Return type for useDialogState hook
+ */
+interface UseDialogStateReturn<T = string> {
+    /** Current dialog state (null when closed) */
+    dialogState: DialogState<T> | null;
+    /**
+     * Function to use as onConfirm callback.
+     * Returns a Promise that resolves when user confirms/cancels.
+     */
+    confirm: (message: T) => Promise<boolean>;
+    /** Close dialog with confirmation (allows navigation) */
+    onConfirm: () => void;
+    /** Close dialog with cancellation (blocks navigation) */
+    onCancel: () => void;
+}
+/**
+ * Hook to manage custom confirmation dialog state.
+ *
+ * Simplifies integration with custom dialog components when using
+ * navigation blocking with `onConfirm` callback.
+ *
+ * @template T - Type of message/data to pass to dialog (defaults to string)
+ * @returns Object with dialog state and control functions
+ *
+ * @example
+ * ```tsx
+ * function MyForm() {
+ *   const [isDirty, setIsDirty] = useState(false);
+ *   const { dialogState, confirm, onConfirm, onCancel } = useDialogState();
+ *
+ *   useNavigationBlocker({
+ *     when: isDirty,
+ *     message: 'Unsaved changes',
+ *     onConfirm: confirm,
+ *   });
+ *
+ *   return (
+ *     <>
+ *       <form>...</form>
+ *       {dialogState && (
+ *         <ConfirmDialog
+ *           message={dialogState.message}
+ *           onConfirm={onConfirm}
+ *           onCancel={onCancel}
+ *         />
+ *       )}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With Material-UI
+ * import { Dialog, DialogTitle, DialogActions, Button } from '@mui/material';
+ *
+ * function EditPage() {
+ *   const { dialogState, confirm, onConfirm, onCancel } = useDialogState();
+ *
+ *   useNavigationBlocker({
+ *     when: hasChanges,
+ *     onConfirm: confirm,
+ *   });
+ *
+ *   return (
+ *     <Dialog open={dialogState?.isOpen ?? false}>
+ *       <DialogTitle>{dialogState?.message}</DialogTitle>
+ *       <DialogActions>
+ *         <Button onClick={onCancel}>Stay</Button>
+ *         <Button onClick={onConfirm}>Leave</Button>
+ *       </DialogActions>
+ *     </Dialog>
+ *   );
+ * }
+ * ```
+ */
+declare function useDialogState<T = string>(): UseDialogStateReturn<T>;
+
+/**
+ * Resolves a condition value (boolean or function returning boolean)
+ *
+ * @param condition - Boolean value or function
+ * @returns Resolved boolean value
+ */
+declare function resolveCondition(condition: boolean | (() => boolean)): boolean;
+/**
+ * Generates a unique blocker ID based on scope and timestamp
+ *
+ * @param prefix - Prefix for the ID
+ * @param scope - Optional scope
+ * @returns Unique blocker ID
+ */
+declare function createBlockerId(prefix: string, scope?: string | Array<string>): string;
+/**
+ * Checks if a value is defined and not empty
+ *
+ * @param value - Value to check
+ * @returns True if value is defined and not empty
+ */
+declare function isDefined<T>(value: T | undefined | null): value is T;
+/**
+ * Normalizes scope to an array
+ *
+ * @param scope - String or array of strings
+ * @returns Array of scope strings
+ */
+declare function normalizeScope(scope: string | Array<string> | undefined): Array<string>;
+
+export { type DialogState, type UseDialogStateReturn, createBlockerId, isDefined, normalizeScope, resolveCondition, useBeforeUnload, useDialogState };

package/dist/index.d.ts

@@ -0,0 +1,158 @@
+export { B as BaseNavigationBlockerOptions, a as BeforeUnloadOptions, N as NavigationBlockerReturn } from './types-C3CPuZip.js';
+
+/**
+ * Blocks browser tab close/refresh when condition is met.
+ *
+ * This hook adds a `beforeunload` event listener to warn users
+ * before they close or refresh the browser tab. Modern browsers
+ * may ignore custom messages and show their own generic warning.
+ *
+ * @param when - Boolean or function returning boolean to determine if blocking should be active
+ * @param message - Optional custom message (may be ignored by browsers)
+ *
+ * @example
+ * ```tsx
+ * function MyForm() {
+ *   const [hasUnsavedChanges, setHasUnsavedChanges] = useState(false);
+ *
+ *   useBeforeUnload(hasUnsavedChanges, 'You have unsaved changes');
+ *
+ *   return <form>...</form>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With function condition
+ * function EditPage() {
+ *   const isFormDirty = useIsBlocked('form');
+ *
+ *   useBeforeUnload(() => isFormDirty);
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+declare function useBeforeUnload(when: boolean | (() => boolean), message?: string): void;
+
+/**
+ * State object for a confirmation dialog
+ */
+interface DialogState<T = string> {
+    /** Whether the dialog is currently open */
+    isOpen: boolean;
+    /** The data to display in the dialog (typically a message) */
+    message: T;
+    /** Resolver function to confirm/cancel navigation */
+    resolve: (confirmed: boolean) => void;
+}
+/**
+ * Return type for useDialogState hook
+ */
+interface UseDialogStateReturn<T = string> {
+    /** Current dialog state (null when closed) */
+    dialogState: DialogState<T> | null;
+    /**
+     * Function to use as onConfirm callback.
+     * Returns a Promise that resolves when user confirms/cancels.
+     */
+    confirm: (message: T) => Promise<boolean>;
+    /** Close dialog with confirmation (allows navigation) */
+    onConfirm: () => void;
+    /** Close dialog with cancellation (blocks navigation) */
+    onCancel: () => void;
+}
+/**
+ * Hook to manage custom confirmation dialog state.
+ *
+ * Simplifies integration with custom dialog components when using
+ * navigation blocking with `onConfirm` callback.
+ *
+ * @template T - Type of message/data to pass to dialog (defaults to string)
+ * @returns Object with dialog state and control functions
+ *
+ * @example
+ * ```tsx
+ * function MyForm() {
+ *   const [isDirty, setIsDirty] = useState(false);
+ *   const { dialogState, confirm, onConfirm, onCancel } = useDialogState();
+ *
+ *   useNavigationBlocker({
+ *     when: isDirty,
+ *     message: 'Unsaved changes',
+ *     onConfirm: confirm,
+ *   });
+ *
+ *   return (
+ *     <>
+ *       <form>...</form>
+ *       {dialogState && (
+ *         <ConfirmDialog
+ *           message={dialogState.message}
+ *           onConfirm={onConfirm}
+ *           onCancel={onCancel}
+ *         />
+ *       )}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With Material-UI
+ * import { Dialog, DialogTitle, DialogActions, Button } from '@mui/material';
+ *
+ * function EditPage() {
+ *   const { dialogState, confirm, onConfirm, onCancel } = useDialogState();
+ *
+ *   useNavigationBlocker({
+ *     when: hasChanges,
+ *     onConfirm: confirm,
+ *   });
+ *
+ *   return (
+ *     <Dialog open={dialogState?.isOpen ?? false}>
+ *       <DialogTitle>{dialogState?.message}</DialogTitle>
+ *       <DialogActions>
+ *         <Button onClick={onCancel}>Stay</Button>
+ *         <Button onClick={onConfirm}>Leave</Button>
+ *       </DialogActions>
+ *     </Dialog>
+ *   );
+ * }
+ * ```
+ */
+declare function useDialogState<T = string>(): UseDialogStateReturn<T>;
+
+/**
+ * Resolves a condition value (boolean or function returning boolean)
+ *
+ * @param condition - Boolean value or function
+ * @returns Resolved boolean value
+ */
+declare function resolveCondition(condition: boolean | (() => boolean)): boolean;
+/**
+ * Generates a unique blocker ID based on scope and timestamp
+ *
+ * @param prefix - Prefix for the ID
+ * @param scope - Optional scope
+ * @returns Unique blocker ID
+ */
+declare function createBlockerId(prefix: string, scope?: string | Array<string>): string;
+/**
+ * Checks if a value is defined and not empty
+ *
+ * @param value - Value to check
+ * @returns True if value is defined and not empty
+ */
+declare function isDefined<T>(value: T | undefined | null): value is T;
+/**
+ * Normalizes scope to an array
+ *
+ * @param scope - String or array of strings
+ * @returns Array of scope strings
+ */
+declare function normalizeScope(scope: string | Array<string> | undefined): Array<string>;
+
+export { type DialogState, type UseDialogStateReturn, createBlockerId, isDefined, normalizeScope, resolveCondition, useBeforeUnload, useDialogState };

package/dist/index.js

@@ -0,0 +1,84 @@
+import { useEffect, useState, useRef, useCallback } from 'react';
+
+// src/core/useBeforeUnload.ts
+
+// src/core/utils.ts
+function resolveCondition(condition) {
+  return typeof condition === "function" ? condition() : condition;
+}
+function createBlockerId(prefix, scope) {
+  const scopePart = scope ? `-${Array.isArray(scope) ? scope.join("-") : scope}` : "";
+  const timestamp = String(Date.now());
+  return `${prefix}${scopePart}-${timestamp}`;
+}
+function isDefined(value) {
+  return value !== void 0 && value !== null;
+}
+function normalizeScope(scope) {
+  if (!scope) {
+    return [];
+  }
+  return Array.isArray(scope) ? scope : [scope];
+}
+
+// src/core/useBeforeUnload.ts
+var DEFAULT_UNLOAD_MESSAGE = "Changes you made may not be saved.";
+function useBeforeUnload(when, message = DEFAULT_UNLOAD_MESSAGE) {
+  useEffect(() => {
+    const shouldBlock = resolveCondition(when);
+    if (!shouldBlock) {
+      return;
+    }
+    const handleBeforeUnload = (event) => {
+      event.preventDefault();
+      if ("returnValue" in event) {
+        event.returnValue = message;
+      }
+    };
+    window.addEventListener("beforeunload", handleBeforeUnload);
+    return () => {
+      window.removeEventListener("beforeunload", handleBeforeUnload);
+    };
+  }, [when, message]);
+}
+function useDialogState() {
+  const [dialogState, setDialogState] = useState(null);
+  const resolveRef = useRef(null);
+  const confirm = useCallback((message) => {
+    return new Promise((resolve) => {
+      if (resolveRef.current) {
+        resolveRef.current(false);
+      }
+      resolveRef.current = resolve;
+      setDialogState({
+        isOpen: true,
+        message,
+        resolve
+      });
+    });
+  }, []);
+  const closeDialog = useCallback((confirmed) => {
+    const resolve = resolveRef.current;
+    if (resolve) {
+      resolve(confirmed);
+    }
+    resolveRef.current = null;
+    setDialogState(null);
+  }, []);
+  const onConfirm = useCallback(() => {
+    closeDialog(true);
+  }, [closeDialog]);
+  const onCancel = useCallback(() => {
+    closeDialog(false);
+  }, [closeDialog]);
+  return {
+    dialogState,
+    confirm,
+    onConfirm,
+    onCancel
+  };
+}
+
+export { createBlockerId, isDefined, normalizeScope, resolveCondition, useBeforeUnload, useDialogState };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/utils.ts","../src/core/useBeforeUnload.ts","../src/core/useDialogState.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Resolves a condition value (boolean or function returning boolean)\n *\n * @param condition - Boolean value or function\n * @returns Resolved boolean value\n */\nexport function resolveCondition(condition: boolean | (() => boolean)): boolean {\n  return typeof condition === \"function\" ? condition() : condition;\n}\n\ninterface Thenable {\n  then: (...args: Array<unknown>) => unknown;\n}\n\nconst hasThen = (value: unknown): value is Thenable =>\n  typeof value === \"object\" && value !== null && \"then\" in value;\n\n/**\n * Checks if a value behaves like a Promise (thenable)\n */\nexport function isThenable<T>(value: unknown): value is PromiseLike<T> {\n  if (!hasThen(value)) {\n    return false;\n  }\n  return typeof value.then === \"function\";\n}\n\nexport interface ConfirmResultSync {\n  kind: \"sync\";\n  confirmed: boolean;\n}\n\nexport interface ConfirmResultAsync {\n  kind: \"async\";\n  promise: Promise<boolean>;\n}\n\nexport type ConfirmResult = ConfirmResultSync | ConfirmResultAsync;\n\n/**\n * Normalizes custom confirm result into sync or async branch.\n */\nexport function resolveConfirmResult(\n  message: string,\n  onConfirm: ((message: string) => boolean | PromiseLike<boolean>) | undefined,\n  fallbackConfirm: (message: string) => boolean\n): ConfirmResult {\n  if (!onConfirm) {\n    return { kind: \"sync\", confirmed: fallbackConfirm(message) };\n  }\n\n  const result = onConfirm(message);\n  if (isThenable<boolean>(result)) {\n    return { kind: \"async\", promise: Promise.resolve(result) };\n  }\n\n  return { kind: \"sync\", confirmed: result };\n}\n\n/**\n * Generates a unique blocker ID based on scope and timestamp\n *\n * @param prefix - Prefix for the ID\n * @param scope - Optional scope\n * @returns Unique blocker ID\n */\nexport function createBlockerId(prefix: string, scope?: string | Array<string>): string {\n  const scopePart = scope ? `-${Array.isArray(scope) ? scope.join(\"-\") : scope}` : \"\";\n  const timestamp = String(Date.now());\n  return `${prefix}${scopePart}-${timestamp}`;\n}\n\n/**\n * Checks if a value is defined and not empty\n *\n * @param value - Value to check\n * @returns True if value is defined and not empty\n */\nexport function isDefined<T>(value: T | undefined | null): value is T {\n  return value !== undefined && value !== null;\n}\n\n/**\n * Normalizes scope to an array\n *\n * @param scope - String or array of strings\n * @returns Array of scope strings\n */\nexport function normalizeScope(scope: string | Array<string> | undefined): Array<string> {\n  if (!scope) {\n    return [];\n  }\n  return Array.isArray(scope) ? scope : [scope];\n}\n","import { useEffect } from \"react\";\nimport { resolveCondition } from \"./utils\";\n\n/**\n * Default message shown when preventing browser unload\n */\nexport const DEFAULT_UNLOAD_MESSAGE = \"Changes you made may not be saved.\";\n\n/**\n * Blocks browser tab close/refresh when condition is met.\n *\n * This hook adds a `beforeunload` event listener to warn users\n * before they close or refresh the browser tab. Modern browsers\n * may ignore custom messages and show their own generic warning.\n *\n * @param when - Boolean or function returning boolean to determine if blocking should be active\n * @param message - Optional custom message (may be ignored by browsers)\n *\n * @example\n * ```tsx\n * function MyForm() {\n *   const [hasUnsavedChanges, setHasUnsavedChanges] = useState(false);\n *\n *   useBeforeUnload(hasUnsavedChanges, 'You have unsaved changes');\n *\n *   return <form>...</form>;\n * }\n * ```\n *\n * @example\n * ```tsx\n * // With function condition\n * function EditPage() {\n *   const isFormDirty = useIsBlocked('form');\n *\n *   useBeforeUnload(() => isFormDirty);\n *\n *   return <div>...</div>;\n * }\n * ```\n */\nexport function useBeforeUnload(\n  when: boolean | (() => boolean),\n  message = DEFAULT_UNLOAD_MESSAGE\n): void {\n  useEffect(() => {\n    const shouldBlock = resolveCondition(when);\n\n    if (!shouldBlock) {\n      return;\n    }\n\n    const handleBeforeUnload = (event: BeforeUnloadEvent): void => {\n      // Prevent default to trigger the browser's confirmation dialog\n      event.preventDefault();\n\n      // Fallback for legacy browsers/WebViews that still rely on returnValue.\n      if (\"returnValue\" in event) {\n        // eslint-disable-next-line @typescript-eslint/no-deprecated\n        event.returnValue = message;\n      }\n    };\n\n    window.addEventListener(\"beforeunload\", handleBeforeUnload);\n\n    return () => {\n      window.removeEventListener(\"beforeunload\", handleBeforeUnload);\n    };\n  }, [when, message]);\n}\n","import { useCallback, useRef, useState } from \"react\";\n\n/**\n * State object for a confirmation dialog\n */\nexport interface DialogState<T = string> {\n  /** Whether the dialog is currently open */\n  isOpen: boolean;\n\n  /** The data to display in the dialog (typically a message) */\n  message: T;\n\n  /** Resolver function to confirm/cancel navigation */\n  resolve: (confirmed: boolean) => void;\n}\n\n/**\n * Return type for useDialogState hook\n */\nexport interface UseDialogStateReturn<T = string> {\n  /** Current dialog state (null when closed) */\n  dialogState: DialogState<T> | null;\n\n  /**\n   * Function to use as onConfirm callback.\n   * Returns a Promise that resolves when user confirms/cancels.\n   */\n  confirm: (message: T) => Promise<boolean>;\n\n  /** Close dialog with confirmation (allows navigation) */\n  onConfirm: () => void;\n\n  /** Close dialog with cancellation (blocks navigation) */\n  onCancel: () => void;\n}\n\n/**\n * Hook to manage custom confirmation dialog state.\n *\n * Simplifies integration with custom dialog components when using\n * navigation blocking with `onConfirm` callback.\n *\n * @template T - Type of message/data to pass to dialog (defaults to string)\n * @returns Object with dialog state and control functions\n *\n * @example\n * ```tsx\n * function MyForm() {\n *   const [isDirty, setIsDirty] = useState(false);\n *   const { dialogState, confirm, onConfirm, onCancel } = useDialogState();\n *\n *   useNavigationBlocker({\n *     when: isDirty,\n *     message: 'Unsaved changes',\n *     onConfirm: confirm,\n *   });\n *\n *   return (\n *     <>\n *       <form>...</form>\n *       {dialogState && (\n *         <ConfirmDialog\n *           message={dialogState.message}\n *           onConfirm={onConfirm}\n *           onCancel={onCancel}\n *         />\n *       )}\n *     </>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // With Material-UI\n * import { Dialog, DialogTitle, DialogActions, Button } from '@mui/material';\n *\n * function EditPage() {\n *   const { dialogState, confirm, onConfirm, onCancel } = useDialogState();\n *\n *   useNavigationBlocker({\n *     when: hasChanges,\n *     onConfirm: confirm,\n *   });\n *\n *   return (\n *     <Dialog open={dialogState?.isOpen ?? false}>\n *       <DialogTitle>{dialogState?.message}</DialogTitle>\n *       <DialogActions>\n *         <Button onClick={onCancel}>Stay</Button>\n *         <Button onClick={onConfirm}>Leave</Button>\n *       </DialogActions>\n *     </Dialog>\n *   );\n * }\n * ```\n */\nexport function useDialogState<T = string>(): UseDialogStateReturn<T> {\n  const [dialogState, setDialogState] = useState<DialogState<T> | null>(null);\n  const resolveRef = useRef<DialogState<T>[\"resolve\"] | null>(null);\n\n  const confirm = useCallback((message: T): Promise<boolean> => {\n    return new Promise<boolean>((resolve) => {\n      if (resolveRef.current) {\n        resolveRef.current(false);\n      }\n      resolveRef.current = resolve;\n      setDialogState({\n        isOpen: true,\n        message,\n        resolve,\n      });\n    });\n  }, []);\n\n  const closeDialog = useCallback((confirmed: boolean) => {\n    const resolve = resolveRef.current;\n    if (resolve) {\n      resolve(confirmed);\n    }\n    resolveRef.current = null;\n    setDialogState(null);\n  }, []);\n\n  const onConfirm = useCallback(() => {\n    closeDialog(true);\n  }, [closeDialog]);\n\n  const onCancel = useCallback(() => {\n    closeDialog(false);\n  }, [closeDialog]);\n\n  return {\n    dialogState,\n    confirm,\n    onConfirm,\n    onCancel,\n  };\n}\n"]}

package/dist/nextjs/index.cjs

@@ -0,0 +1,178 @@
+'use strict';
+
+var router = require('next/router');
+var react = require('react');
+var reactActionGuard = require('@okyrychenko-dev/react-action-guard');
+
+// src/nextjs/usePagesRouterBlocker.ts
+
+// src/core/utils.ts
+function resolveCondition(condition) {
+  return typeof condition === "function" ? condition() : condition;
+}
+var hasThen = (value) => typeof value === "object" && value !== null && "then" in value;
+function isThenable(value) {
+  if (!hasThen(value)) {
+    return false;
+  }
+  return typeof value.then === "function";
+}
+function resolveConfirmResult(message, onConfirm, fallbackConfirm) {
+  if (!onConfirm) {
+    return { kind: "sync", confirmed: fallbackConfirm(message) };
+  }
+  const result = onConfirm(message);
+  if (isThenable(result)) {
+    return { kind: "async", promise: Promise.resolve(result) };
+  }
+  return { kind: "sync", confirmed: result };
+}
+function isDefined(value) {
+  return value !== void 0 && value !== null;
+}
+function normalizeScope(scope) {
+  if (!scope) {
+    return [];
+  }
+  return Array.isArray(scope) ? scope : [scope];
+}
+
+// src/core/useBeforeUnload.ts
+var DEFAULT_UNLOAD_MESSAGE = "Changes you made may not be saved.";
+function useBeforeUnload(when, message = DEFAULT_UNLOAD_MESSAGE) {
+  react.useEffect(() => {
+    const shouldBlock = resolveCondition(when);
+    if (!shouldBlock) {
+      return;
+    }
+    const handleBeforeUnload = (event) => {
+      event.preventDefault();
+      if ("returnValue" in event) {
+        event.returnValue = message;
+      }
+    };
+    window.addEventListener("beforeunload", handleBeforeUnload);
+    return () => {
+      window.removeEventListener("beforeunload", handleBeforeUnload);
+    };
+  }, [when, message]);
+}
+function useShouldBlock(when, scope) {
+  const scopes = react.useMemo(() => normalizeScope(scope), [scope]);
+  const isScopeBlocked = reactActionGuard.useIsBlocked(scopes.length === 1 ? scopes[0] : scopes);
+  const warnedMissingConditionRef = react.useRef(false);
+  const warnedFunctionRef = react.useRef(false);
+  react.useEffect(() => {
+    if (process.env.NODE_ENV !== "development") {
+      return;
+    }
+    if (!warnedMissingConditionRef.current && !isDefined(when) && !scope) {
+      warnedMissingConditionRef.current = true;
+      console.warn(
+        '[react-action-guard-router] useShouldBlock: Neither "when" nor "scope" provided. This hook will always return false. Please provide at least one condition.'
+      );
+    }
+    if (!warnedFunctionRef.current && typeof when === "function") {
+      warnedFunctionRef.current = true;
+      console.warn(
+        '[react-action-guard-router] useShouldBlock: "when" is a function. Make sure to wrap it with useCallback to avoid unnecessary re-computations.'
+      );
+    }
+  }, [when, scope]);
+  const shouldBlock = react.useMemo(() => {
+    let blockCondition = false;
+    if (isDefined(when)) {
+      blockCondition = resolveCondition(when);
+    }
+    if (scope && isScopeBlocked) {
+      blockCondition = true;
+    }
+    return blockCondition;
+  }, [when, scope, isScopeBlocked]);
+  return shouldBlock;
+}
+
+// src/core/constants.ts
+var ROUTE_ERRORS = {
+  /** Route change was aborted by the user */
+  ABORTED: "Route change aborted by user",
+  /** Route change was blocked */
+  BLOCKED: "Route change blocked"
+};
+
+// src/nextjs/usePagesRouterBlocker.ts
+function useNavigationBlocker(options) {
+  const { when, scope, message, onBlock, onAllow, blockBrowserUnload = true, onConfirm } = options;
+  const router$1 = router.useRouter();
+  const allowNextUrlRef = react.useRef(null);
+  const shouldBlock = useShouldBlock(when, scope);
+  react.useEffect(() => {
+    if (!shouldBlock) {
+      return;
+    }
+    const handleRouteChangeStart = (url) => {
+      if (allowNextUrlRef.current === url) {
+        allowNextUrlRef.current = null;
+        onAllow?.();
+        return;
+      }
+      onBlock?.();
+      if (!message) {
+        router$1.events.emit("routeChangeError");
+        throw new Error(ROUTE_ERRORS.BLOCKED);
+      }
+      const confirmation = resolveConfirmResult(
+        message,
+        onConfirm,
+        (value) => window.confirm(value)
+      );
+      if (confirmation.kind === "sync" && !confirmation.confirmed) {
+        router$1.events.emit("routeChangeError");
+        throw new Error(ROUTE_ERRORS.ABORTED);
+      }
+      if (confirmation.kind === "sync") {
+        onAllow?.();
+        return;
+      }
+      router$1.events.emit("routeChangeError");
+      confirmation.promise.then((confirmed) => {
+        if (confirmed) {
+          allowNextUrlRef.current = url;
+          onAllow?.();
+          void router$1.push(url);
+        }
+      }).catch(() => {
+      });
+      throw new Error(ROUTE_ERRORS.ABORTED);
+    };
+    router$1.events.on("routeChangeStart", handleRouteChangeStart);
+    return () => {
+      router$1.events.off("routeChangeStart", handleRouteChangeStart);
+    };
+  }, [shouldBlock, message, onBlock, onAllow, router$1, onConfirm]);
+  useBeforeUnload(blockBrowserUnload && shouldBlock, message ?? DEFAULT_UNLOAD_MESSAGE);
+  return {
+    isBlocking: shouldBlock
+  };
+}
+function useNavigationBlocker2(options) {
+  const { when, scope, message, blockBrowserUnload = true } = options;
+  const shouldBlock = useShouldBlock(when, scope);
+  react.useEffect(() => {
+    if (process.env.NODE_ENV === "development" && shouldBlock) {
+      console.warn(
+        "[react-action-guard-router] App Router has limited blocking support. Link clicks cannot be blocked. Use Pages Router for full support."
+      );
+    }
+  }, [shouldBlock]);
+  useBeforeUnload(blockBrowserUnload && shouldBlock, message ?? DEFAULT_UNLOAD_MESSAGE);
+  return {
+    isBlocking: shouldBlock
+  };
+}
+
+exports.useAppRouterBlocker = useNavigationBlocker2;
+exports.useNavigationBlocker = useNavigationBlocker;
+exports.usePagesRouterBlocker = useNavigationBlocker;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/nextjs/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/utils.ts","../../src/core/useBeforeUnload.ts","../../src/core/useShouldBlock.ts","../../src/core/constants.ts","../../src/nextjs/usePagesRouterBlocker.ts","../../src/nextjs/useAppRouterBlocker.ts"],"names":["useEffect","useMemo","useIsBlocked","useRef","router","useRouter","useNavigationBlocker"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Resolves a condition value (boolean or function returning boolean)\n *\n * @param condition - Boolean value or function\n * @returns Resolved boolean value\n */\nexport function resolveCondition(condition: boolean | (() => boolean)): boolean {\n  return typeof condition === \"function\" ? condition() : condition;\n}\n\ninterface Thenable {\n  then: (...args: Array<unknown>) => unknown;\n}\n\nconst hasThen = (value: unknown): value is Thenable =>\n  typeof value === \"object\" && value !== null && \"then\" in value;\n\n/**\n * Checks if a value behaves like a Promise (thenable)\n */\nexport function isThenable<T>(value: unknown): value is PromiseLike<T> {\n  if (!hasThen(value)) {\n    return false;\n  }\n  return typeof value.then === \"function\";\n}\n\nexport interface ConfirmResultSync {\n  kind: \"sync\";\n  confirmed: boolean;\n}\n\nexport interface ConfirmResultAsync {\n  kind: \"async\";\n  promise: Promise<boolean>;\n}\n\nexport type ConfirmResult = ConfirmResultSync | ConfirmResultAsync;\n\n/**\n * Normalizes custom confirm result into sync or async branch.\n */\nexport function resolveConfirmResult(\n  message: string,\n  onConfirm: ((message: string) => boolean | PromiseLike<boolean>) | undefined,\n  fallbackConfirm: (message: string) => boolean\n): ConfirmResult {\n  if (!onConfirm) {\n    return { kind: \"sync\", confirmed: fallbackConfirm(message) };\n  }\n\n  const result = onConfirm(message);\n  if (isThenable<boolean>(result)) {\n    return { kind: \"async\", promise: Promise.resolve(result) };\n  }\n\n  return { kind: \"sync\", confirmed: result };\n}\n\n/**\n * Generates a unique blocker ID based on scope and timestamp\n *\n * @param prefix - Prefix for the ID\n * @param scope - Optional scope\n * @returns Unique blocker ID\n */\nexport function createBlockerId(prefix: string, scope?: string | Array<string>): string {\n  const scopePart = scope ? `-${Array.isArray(scope) ? scope.join(\"-\") : scope}` : \"\";\n  const timestamp = String(Date.now());\n  return `${prefix}${scopePart}-${timestamp}`;\n}\n\n/**\n * Checks if a value is defined and not empty\n *\n * @param value - Value to check\n * @returns True if value is defined and not empty\n */\nexport function isDefined<T>(value: T | undefined | null): value is T {\n  return value !== undefined && value !== null;\n}\n\n/**\n * Normalizes scope to an array\n *\n * @param scope - String or array of strings\n * @returns Array of scope strings\n */\nexport function normalizeScope(scope: string | Array<string> | undefined): Array<string> {\n  if (!scope) {\n    return [];\n  }\n  return Array.isArray(scope) ? scope : [scope];\n}\n","import { useEffect } from \"react\";\nimport { resolveCondition } from \"./utils\";\n\n/**\n * Default message shown when preventing browser unload\n */\nexport const DEFAULT_UNLOAD_MESSAGE = \"Changes you made may not be saved.\";\n\n/**\n * Blocks browser tab close/refresh when condition is met.\n *\n * This hook adds a `beforeunload` event listener to warn users\n * before they close or refresh the browser tab. Modern browsers\n * may ignore custom messages and show their own generic warning.\n *\n * @param when - Boolean or function returning boolean to determine if blocking should be active\n * @param message - Optional custom message (may be ignored by browsers)\n *\n * @example\n * ```tsx\n * function MyForm() {\n *   const [hasUnsavedChanges, setHasUnsavedChanges] = useState(false);\n *\n *   useBeforeUnload(hasUnsavedChanges, 'You have unsaved changes');\n *\n *   return <form>...</form>;\n * }\n * ```\n *\n * @example\n * ```tsx\n * // With function condition\n * function EditPage() {\n *   const isFormDirty = useIsBlocked('form');\n *\n *   useBeforeUnload(() => isFormDirty);\n *\n *   return <div>...</div>;\n * }\n * ```\n */\nexport function useBeforeUnload(\n  when: boolean | (() => boolean),\n  message = DEFAULT_UNLOAD_MESSAGE\n): void {\n  useEffect(() => {\n    const shouldBlock = resolveCondition(when);\n\n    if (!shouldBlock) {\n      return;\n    }\n\n    const handleBeforeUnload = (event: BeforeUnloadEvent): void => {\n      // Prevent default to trigger the browser's confirmation dialog\n      event.preventDefault();\n\n      // Fallback for legacy browsers/WebViews that still rely on returnValue.\n      if (\"returnValue\" in event) {\n        // eslint-disable-next-line @typescript-eslint/no-deprecated\n        event.returnValue = message;\n      }\n    };\n\n    window.addEventListener(\"beforeunload\", handleBeforeUnload);\n\n    return () => {\n      window.removeEventListener(\"beforeunload\", handleBeforeUnload);\n    };\n  }, [when, message]);\n}\n","import { useIsBlocked } from \"@okyrychenko-dev/react-action-guard\";\nimport { useEffect, useMemo, useRef } from \"react\";\nimport { isDefined, normalizeScope, resolveCondition } from \"./utils\";\n\n/**\n * Shared hook to determine if blocking should be active based on\n * condition and/or scope state.\n *\n * This hook uses `useMemo` for optimal performance, ensuring blocking state\n * is computed synchronously without additional re-renders.\n *\n * @param when - Optional condition (boolean or function)\n * @param scope - Optional scope(s) to check\n * @returns Whether blocking should be active\n *\n * @internal\n */\nexport function useShouldBlock(\n  when?: boolean | (() => boolean),\n  scope?: string | Array<string>\n): boolean {\n  // Memoize scope normalization to avoid recalculation on every render\n  const scopes = useMemo(() => normalizeScope(scope), [scope]);\n\n  // Check if any specified scopes are blocked\n  const isScopeBlocked = useIsBlocked(scopes.length === 1 ? scopes[0] : scopes);\n\n  // Development-only validation\n  const warnedMissingConditionRef = useRef(false);\n  const warnedFunctionRef = useRef(false);\n\n  useEffect(() => {\n    if (process.env.NODE_ENV !== \"development\") {\n      return;\n    }\n\n    if (!warnedMissingConditionRef.current && !isDefined(when) && !scope) {\n      warnedMissingConditionRef.current = true;\n      console.warn(\n        '[react-action-guard-router] useShouldBlock: Neither \"when\" nor \"scope\" provided. ' +\n          \"This hook will always return false. Please provide at least one condition.\"\n      );\n    }\n\n    if (!warnedFunctionRef.current && typeof when === \"function\") {\n      warnedFunctionRef.current = true;\n      console.warn(\n        '[react-action-guard-router] useShouldBlock: \"when\" is a function. ' +\n          \"Make sure to wrap it with useCallback to avoid unnecessary re-computations.\"\n      );\n    }\n  }, [when, scope]);\n\n  // Compute blocking state synchronously using useMemo\n  // This avoids the useState + useEffect pattern which causes an extra render\n  const shouldBlock = useMemo(() => {\n    let blockCondition = false;\n\n    // Check manual condition\n    if (isDefined(when)) {\n      blockCondition = resolveCondition(when);\n    }\n\n    // Check scope-based blocking (OR logic - block if either condition is true)\n    if (scope && isScopeBlocked) {\n      blockCondition = true;\n    }\n\n    return blockCondition;\n  }, [when, scope, isScopeBlocked]);\n\n  return shouldBlock;\n}\n","/**\n * Error messages for route blocking\n */\nexport const ROUTE_ERRORS = {\n  /** Route change was aborted by the user */\n  ABORTED: \"Route change aborted by user\",\n  /** Route change was blocked */\n  BLOCKED: \"Route change blocked\",\n} as const;\n","import { useRouter } from \"next/router\";\nimport { useEffect, useRef } from \"react\";\nimport {\n  DEFAULT_UNLOAD_MESSAGE,\n  ROUTE_ERRORS,\n  resolveConfirmResult,\n  useBeforeUnload,\n  useShouldBlock,\n} from \"../core\";\nimport type { UseNavigationBlockerOptions } from \"./types\";\nimport type { NavigationBlockerReturn } from \"../core/types\";\n\n/**\n * Blocks navigation in Next.js Pages Router applications.\n *\n * This hook integrates with Next.js Pages Router's route change events and\n * react-action-guard's scope system to prevent navigation when certain conditions\n * are met or when specific scopes are blocked.\n *\n * **Note:** This hook ONLY works with Next.js Pages Router (pages/ directory).\n * For App Router, use the App Router adapter instead.\n *\n * **Features:**\n * - Block navigation based on boolean condition or function\n * - Automatically block when react-action-guard scopes are active\n * - Support for browser `beforeunload` event (tab close/refresh)\n * - Customizable confirmation dialog\n * - Callbacks for block/allow events\n *\n * **Custom confirm note:**\n * Async `onConfirm` is supported, but Pages Router requires a re-attempted\n * navigation after confirmation (via `router.push(url)` with default options).\n *\n * ⚠️ **Limitation:** When using async `onConfirm`, the re-attempted navigation\n * uses default options. Original `as`, `shallow`, `locale`, and `scroll` params\n * may be lost because Next.js Pages Router does not expose these in\n * the `routeChangeStart` event. For precise control, use synchronous confirmations.\n *\n * @param options - Configuration options\n * @returns Object with `isBlocking` state\n *\n * @example\n * ```tsx\n * // pages/edit.tsx\n * function EditPage() {\n *   const [hasChanges, setHasChanges] = useState(false);\n *\n *   useNavigationBlocker({\n *     when: hasChanges,\n *     message: 'You have unsaved changes. Leave anyway?',\n *   });\n *\n *   return <form>...</form>;\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Block based on scope\n * function CheckoutFlow() {\n *   useNavigationBlocker({\n *     scope: 'checkout',\n *     message: 'Your order is being processed. Please wait.',\n *   });\n * }\n * ```\n */\nexport function useNavigationBlocker(\n  options: UseNavigationBlockerOptions\n): NavigationBlockerReturn {\n  const { when, scope, message, onBlock, onAllow, blockBrowserUnload = true, onConfirm } = options;\n\n  const router = useRouter();\n  const allowNextUrlRef = useRef<string | null>(null);\n\n  // Use shared logic to determine if blocking should be active\n  const shouldBlock = useShouldBlock(when, scope);\n\n  // Block navigation using Next.js router events\n  useEffect(() => {\n    if (!shouldBlock) {\n      return;\n    }\n\n    const handleRouteChangeStart = (url: string): void => {\n      // Early return for allowed URL\n      if (allowNextUrlRef.current === url) {\n        allowNextUrlRef.current = null;\n        onAllow?.();\n        return;\n      }\n\n      // Trigger onBlock callback\n      onBlock?.();\n\n      // If no message, block silently\n      if (!message) {\n        router.events.emit(\"routeChangeError\");\n        throw new Error(ROUTE_ERRORS.BLOCKED);\n      }\n\n      const confirmation = resolveConfirmResult(message, onConfirm, (value) =>\n        window.confirm(value)\n      );\n\n      if (confirmation.kind === \"sync\" && !confirmation.confirmed) {\n        router.events.emit(\"routeChangeError\");\n        throw new Error(ROUTE_ERRORS.ABORTED);\n      }\n\n      if (confirmation.kind === \"sync\") {\n        onAllow?.();\n        return;\n      }\n\n      router.events.emit(\"routeChangeError\");\n      confirmation.promise\n        .then((confirmed) => {\n          if (confirmed) {\n            allowNextUrlRef.current = url;\n            onAllow?.();\n            void router.push(url);\n          }\n        })\n        .catch(() => {\n          // On error, treat as cancelled\n        });\n      throw new Error(ROUTE_ERRORS.ABORTED);\n    };\n\n    router.events.on(\"routeChangeStart\", handleRouteChangeStart);\n\n    return () => {\n      router.events.off(\"routeChangeStart\", handleRouteChangeStart);\n    };\n  }, [shouldBlock, message, onBlock, onAllow, router, onConfirm]);\n\n  // Also block browser unload if requested\n  useBeforeUnload(blockBrowserUnload && shouldBlock, message ?? DEFAULT_UNLOAD_MESSAGE);\n\n  return {\n    isBlocking: shouldBlock,\n  };\n}\n","import { useEffect } from \"react\";\nimport { DEFAULT_UNLOAD_MESSAGE, useBeforeUnload, useShouldBlock } from \"../core\";\nimport type { UseNavigationBlockerOptions } from \"./types\";\nimport type { NavigationBlockerReturn } from \"../core/types\";\n\n/**\n * Blocks navigation in Next.js App Router applications.\n *\n * **⚠️ IMPORTANT LIMITATION:**\n * Next.js App Router (app/ directory) does not currently provide an official API\n * for blocking navigation. This implementation provides best-effort blocking using\n * available mechanisms, but has limitations:\n *\n * - ✅ Browser back/forward buttons are blocked via `beforeunload`\n * - ✅ Tab close/refresh is blocked via `beforeunload`\n * - ❌ Next.js `<Link>` components are NOT blocked\n * - ❌ Programmatic `router.push()` is NOT blocked\n * - ❌ Browser address bar navigation is NOT fully blocked\n *\n * For production use with full blocking capabilities, consider using Pages Router\n * or wait for official Next.js App Router blocking API.\n *\n * @param options - Configuration options\n * @returns Object with `isBlocking` state\n *\n * @example\n * ```tsx\n * // app/edit/page.tsx\n * 'use client';\n *\n * function EditPage() {\n *   const [hasChanges, setHasChanges] = useState(false);\n *\n *   useNavigationBlocker({\n *     when: hasChanges,\n *     message: 'You have unsaved changes.',\n *   });\n *\n *   return <form>...</form>;\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Block based on scope\n * 'use client';\n *\n * function CheckoutFlow() {\n *   useNavigationBlocker({\n *     scope: 'checkout',\n *     message: 'Your order is being processed.',\n *   });\n * }\n * ```\n */\nexport function useNavigationBlocker(\n  options: UseNavigationBlockerOptions\n): NavigationBlockerReturn {\n  const { when, scope, message, blockBrowserUnload = true } = options;\n\n  // Use shared logic to determine if blocking should be active\n  const shouldBlock = useShouldBlock(when, scope);\n\n  // Log warning in development\n  useEffect(() => {\n    if (process.env.NODE_ENV === \"development\" && shouldBlock) {\n      console.warn(\n        \"[react-action-guard-router] App Router has limited blocking support. \" +\n          \"Link clicks cannot be blocked. Use Pages Router for full support.\"\n      );\n    }\n  }, [shouldBlock]);\n\n  // Best effort: Block browser navigation via beforeunload\n  // This will prevent tab close, refresh, and some browser back/forward\n  useBeforeUnload(blockBrowserUnload && shouldBlock, message ?? DEFAULT_UNLOAD_MESSAGE);\n\n  return {\n    isBlocking: shouldBlock,\n  };\n}\n"]}