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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Oleksii Kyrychenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,519 @@
+# @okyrychenko-dev/react-action-guard-router
+
+[![npm version](https://img.shields.io/npm/v/@okyrychenko-dev/react-action-guard-router.svg)](https://www.npmjs.com/package/@okyrychenko-dev/react-action-guard-router)
+[![npm downloads](https://img.shields.io/npm/dm/@okyrychenko-dev/react-action-guard-router.svg)](https://www.npmjs.com/package/@okyrychenko-dev/react-action-guard-router)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+> Router integration for React Action Guard - navigation blocking for React Router, Remix, TanStack Router, and Next.js
+
+## Features
+
+- 🛣️ **Multi-Router Support** - React Router v6+, Remix, TanStack Router, Next.js Pages Router, and best-effort App Router support
+- 🎯 **Scope-Based Blocking** - Synchronize navigation blocking with UI blocking scopes
+- 🚦 **Condition-Based Blocking** - Block based on boolean conditions or functions
+- 💬 **Custom Dialog Support** - `useDialogState` helper for async confirmation dialogs
+- 🌐 **Browser Protection** - Prevents tab close/refresh with `beforeunload` events
+- 🔄 **Sync & Async Handlers** - Support for both synchronous and Promise-based confirmations
+- 📦 **Tree-Shakeable** - Import only the router adapter you need
+- 🔒 **TypeScript-Friendly** - Strong editor support and typed router adapters
+- 🧹 **Auto Cleanup** - Automatic listener cleanup on component unmount
+
+## Installation
+
+```bash
+npm install @okyrychenko-dev/react-action-guard-router @okyrychenko-dev/react-action-guard
+# or
+yarn add @okyrychenko-dev/react-action-guard-router @okyrychenko-dev/react-action-guard
+# or
+pnpm add @okyrychenko-dev/react-action-guard-router @okyrychenko-dev/react-action-guard
+```
+
+This package requires the following peer dependencies:
+
+- [@okyrychenko-dev/react-action-guard](https://www.npmjs.com/package/@okyrychenko-dev/react-action-guard) ^1.0.1 - The core UI blocking library
+- [React](https://react.dev/) ^18.0.0 || ^19.0.0
+- One of:
+  - [react-router-dom](https://reactrouter.com/) ^6.0.0 - For React Router or Remix
+  - [@tanstack/react-router](https://tanstack.com/router) ^1.0.0 - For TanStack Router
+  - [next](https://nextjs.org/) ^13.4.0 - For Next.js Pages Router and best-effort App Router support
+- [Zustand](https://zustand-demo.pmnd.rs/) - State management (peer dependency of react-action-guard)
+
+## Quick Start
+
+### Basic Usage with react-action-guard
+
+The most powerful pattern - synchronize navigation blocking with UI blocking:
+
+```tsx
+import { useBlocker } from '@okyrychenko-dev/react-action-guard';
+import { useNavigationBlocker } from '@okyrychenko-dev/react-action-guard-router/react-router';
+
+function PaymentForm() {
+  const [isProcessing, setIsProcessing] = useState(false);
+
+  // Block UI during payment processing
+  useBlocker('payment-processing', {
+    scope: 'checkout',
+    reason: 'Processing payment...',
+  }, isProcessing);
+
+  // Block navigation when the same scope is active
+  useNavigationBlocker({
+    scope: 'checkout',
+    message: 'Payment is processing. Please wait.',
+  });
+
+  // When isProcessing = true, both UI and navigation are blocked
+}
+```
+
+### Simple Condition-Based Blocking
+
+For basic usage without react-action-guard scopes:
+
+```tsx
+import { useNavigationBlocker } from '@okyrychenko-dev/react-action-guard-router/react-router';
+
+function EditForm() {
+  const [hasUnsavedChanges, setHasUnsavedChanges] = useState(false);
+
+  useNavigationBlocker({
+    when: hasUnsavedChanges,
+    message: 'You have unsaved changes. Leave anyway?',
+  });
+}
+```
+
+## API Reference
+
+### Hooks
+
+#### `useNavigationBlocker(options)`
+
+Blocks navigation in router applications based on conditions or scope state.
+
+**Parameters:**
+
+- `options: UseNavigationBlockerOptions`
+  - `when?: boolean | (() => boolean)` - Condition to activate blocking
+  - `scope?: string | string[]` - Scope(s) from react-action-guard to monitor
+  - `message?: string` - Confirmation dialog message
+  - `onConfirm?: (message: string) => boolean | PromiseLike<boolean>` - Custom confirmation handler, called once per blocked navigation attempt
+  - `onBlock?: () => void` - Callback when navigation is blocked
+  - `onAllow?: () => void` - Callback when navigation is allowed
+  - `blockBrowserUnload?: boolean` - Block tab close/refresh (default: `true`)
+
+**Returns:** `{ isBlocking: boolean; isIntercepting?: boolean }`
+
+- `isBlocking` - Blocking condition is armed for this adapter
+- `isIntercepting?: boolean` - Active interception state when the router can expose it
+
+**Available in:**
+- `@okyrychenko-dev/react-action-guard-router/react-router` - React Router v6+ & Remix
+- `@okyrychenko-dev/react-action-guard-router/tanstack-router` - TanStack Router
+- `@okyrychenko-dev/react-action-guard-router/nextjs` - Next.js Pages & App Router
+
+**Examples:**
+
+```tsx
+// Scope-based blocking
+useNavigationBlocker({
+  scope: 'form',
+  message: 'You have unsaved changes',
+});
+
+// Condition-based blocking
+useNavigationBlocker({
+  when: hasChanges,
+  message: 'Discard changes?',
+  onBlock: () => console.log('Navigation blocked'),
+  onAllow: () => console.log('Navigation allowed'),
+});
+
+// Multiple scopes
+useNavigationBlocker({
+  scope: ['form', 'validation'],
+  message: 'Form is being validated',
+});
+
+// Function condition
+useNavigationBlocker({
+  when: () => formIsDirty() || hasUnsavedData(),
+  message: 'You have unsaved work',
+});
+```
+
+#### `useDialogState<TMessage = string>()`
+
+Helper hook for managing custom confirmation dialogs.
+
+**Parameters:** None
+
+**Returns:**
+- `dialogState: DialogState<TMessage> | null` - Current dialog state
+  - `message: TMessage` - The message passed to confirm
+  - `isOpen: boolean` - Whether dialog is open
+  - `resolve: (value: boolean) => void` - Internal resolver
+- `confirm: (message: TMessage) => Promise<boolean>` - Show dialog, returns Promise
+- `onConfirm: () => void` - Resolve dialog with `true`
+- `onCancel: () => void` - Resolve dialog with `false`
+
+**Example:**
+
+```tsx
+import { useNavigationBlocker, useDialogState } from '@okyrychenko-dev/react-action-guard-router/react-router';
+
+function MyComponent() {
+  const [hasChanges, setHasChanges] = useState(false);
+  const { dialogState, confirm, onConfirm, onCancel } = useDialogState();
+
+  useNavigationBlocker({
+    when: hasChanges,
+    onConfirm: confirm,  // Returns Promise<boolean>
+  });
+
+  return (
+    <>
+      <form>...</form>
+      {dialogState && (
+        <CustomDialog
+          message={dialogState.message}
+          onConfirm={onConfirm}
+          onCancel={onCancel}
+        />
+      )}
+    </>
+  );
+}
+```
+
+**Custom message types:**
+
+```tsx
+interface CustomMessage {
+  title: string;
+  body: string;
+  severity: 'warning' | 'error';
+}
+
+const { dialogState, confirm } = useDialogState<CustomMessage>();
+
+useNavigationBlocker({
+  when: isDirty,
+  onConfirm: () => confirm({
+    title: 'Unsaved Changes',
+    body: 'Your work will be lost',
+    severity: 'warning',
+  }),
+});
+```
+
+#### `usePrompt(message, when)` (React Router only)
+
+Simple API similar to React Router v5's `usePrompt`.
+
+**Parameters:**
+- `message: string` - Confirmation message
+- `when: boolean` - Condition to activate blocking
+
+**Example:**
+
+```tsx
+import { usePrompt } from '@okyrychenko-dev/react-action-guard-router/react-router';
+
+function MyForm() {
+  const [hasChanges, setHasChanges] = useState(false);
+  usePrompt('You have unsaved changes', hasChanges);
+}
+```
+
+#### `useBeforeUnload(when, message?)`
+
+Standalone hook for blocking browser unload events (tab close, refresh).
+
+**Parameters:**
+- `when: boolean` - Condition to activate blocking
+- `message?: string` - Optional custom message (default: "Are you sure you want to leave?")
+
+**Example:**
+
+```tsx
+import { useBeforeUnload } from '@okyrychenko-dev/react-action-guard-router';
+
+function MyComponent() {
+  const [hasUnsavedWork, setHasUnsavedWork] = useState(false);
+  useBeforeUnload(hasUnsavedWork, 'You have unsaved work');
+}
+```
+
+This utility works independently of any router and can be used in any React application.
+
+---
+
+## Router-Specific Notes
+
+### React Router (& Remix)
+
+Full support with React Router v6's `useBlocker` hook.
+
+```tsx
+import { useNavigationBlocker } from '@okyrychenko-dev/react-action-guard-router/react-router';
+
+function MyComponent() {
+  useNavigationBlocker({
+    when: isDirty,
+    message: 'Discard changes?',
+  });
+}
+```
+
+> **Note:** Remix uses React Router v6 internally, so the React Router adapter works seamlessly in Remix applications.
+> `isIntercepting` is available here because React Router exposes blocker state directly.
+
+### TanStack Router
+
+Full support with TanStack Router's history blocking.
+
+```tsx
+import { useNavigationBlocker } from '@okyrychenko-dev/react-action-guard-router/tanstack-router';
+
+function MyComponent() {
+  useNavigationBlocker({
+    when: isDirty,
+    message: 'Discard changes?',
+  });
+}
+```
+
+Async `onConfirm` is supported and evaluated once per blocked navigation attempt.
+
+### Next.js Pages Router
+
+Full support with Next.js router events.
+
+```tsx
+// pages/edit.tsx
+import { useNavigationBlocker } from '@okyrychenko-dev/react-action-guard-router/nextjs';
+
+function EditPage() {
+  useNavigationBlocker({
+    when: isDirty,
+    message: 'Discard changes?',
+  });
+}
+```
+
+**Async `onConfirm` behavior:**  
+Pages Router does not allow pausing transitions. When you return a Promise from `onConfirm`, the hook cancels the current navigation and re-attempts it via `router.push(url)` if confirmed. This may not preserve original transition options (e.g., `shallow`, `scroll`, `locale`).
+
+### Next.js App Router
+
+Best-effort support only. Browser unload protection works, but App Router does not expose an official navigation-blocking API.
+
+```tsx
+// app/edit/page.tsx
+'use client';
+
+import { useNavigationBlocker } from '@okyrychenko-dev/react-action-guard-router/nextjs';
+
+function EditPage() {
+  useNavigationBlocker({
+    when: isDirty,
+    message: 'You have unsaved changes',
+  });
+}
+```
+
+**App Router Limitations:**
+- ✅ Browser back/forward/close/refresh are blocked
+- ❌ `<Link>` component navigation is NOT blocked
+- ❌ `router.push()` is NOT blocked
+
+For full navigation blocking support, use Pages Router.
+
+## Adapter Capabilities
+
+| Adapter | `isBlocking` meaning | `isIntercepting` | Async `onConfirm` | Caveats |
+| --- | --- | --- | --- | --- |
+| React Router | Blocking condition is armed | Yes | Yes | Best semantic fidelity |
+| TanStack Router | Blocking condition is armed | No | Yes | Depends on history.block integration |
+| Next.js Pages Router | Blocking condition is armed | No | Yes | Re-attempts confirmed navigation with `router.push(url)` |
+| Next.js App Router | Blocking condition is armed | No | Best effort only | No official blocker API from Next.js |
+
+---
+
+## Use Cases
+
+### Form Validation
+
+```tsx
+function SignupForm() {
+  const [formData, setFormData] = useState({});
+  const isDirty = Object.keys(formData).length > 0;
+
+  useNavigationBlocker({
+    when: isDirty,
+    message: 'Your signup progress will be lost. Continue?',
+  });
+}
+```
+
+### Multi-Step Wizard
+
+```tsx
+function MultiStepWizard() {
+  const [currentStep, setCurrentStep] = useState(1);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  // Block UI during submission
+  useBlocker('wizard-submit', {
+    scope: 'wizard',
+    reason: 'Submitting form...',
+  }, isSubmitting);
+
+  // Block navigation during submission OR if wizard incomplete
+  useNavigationBlocker({
+    scope: 'wizard',
+    when: currentStep < 5,
+    message: `You're on step ${currentStep}/5. Exit wizard?`,
+  });
+}
+```
+
+### E-Commerce Checkout
+
+```tsx
+import { useBlockingMutation } from '@okyrychenko-dev/react-action-guard-tanstack';
+import { useNavigationBlocker } from '@okyrychenko-dev/react-action-guard-router/react-router';
+
+function CheckoutPage() {
+  const paymentMutation = useBlockingMutation({
+    mutationFn: processPayment,
+    blockingConfig: { scope: 'checkout' },
+  });
+
+  useNavigationBlocker({
+    scope: 'checkout',
+    message: 'Payment is processing. Leaving will cancel the transaction.',
+  });
+}
+```
+
+### File Upload with Progress
+
+```tsx
+function FileUploader() {
+  const [uploadProgress, setUploadProgress] = useState(0);
+  const isUploading = uploadProgress > 0 && uploadProgress < 100;
+
+  useNavigationBlocker({
+    when: isUploading,
+    message: `Upload ${uploadProgress}% complete. Cancel upload?`,
+    onBlock: () => pauseUpload(),
+  });
+}
+```
+
+---
+
+## TypeScript
+
+TypeScript-friendly API surface:
+
+```typescript
+import type {
+  // Core types
+  UseNavigationBlockerOptions,
+  NavigationBlockerReturn,
+  DialogState,
+  ConfirmationResult,
+  ConfirmationCallbacks,
+} from '@okyrychenko-dev/react-action-guard-router';
+
+// Router-specific types
+import type { UseNavigationBlockerOptions } from '@okyrychenko-dev/react-action-guard-router/react-router';
+```
+
+**Typed scopes with `react-action-guard`:**
+
+```tsx
+import { createTypedHooks } from '@okyrychenko-dev/react-action-guard';
+
+type AppScopes = 'form' | 'checkout' | 'navigation';
+const { useBlocker } = createTypedHooks<AppScopes>();
+
+function MyComponent() {
+  useBlocker('id', { scope: 'form' });  // ✅ Typed in the core package
+
+  useNavigationBlocker({
+    scope: 'form',  // ✅ Reuses the same scope values cleanly
+    message: 'Leave form?',
+  });
+}
+```
+
+---
+
+## Bundle Size
+
+Tree-shakeable by router adapter. Import only what you need:
+
+```tsx
+// Only React Router code is bundled
+import { useNavigationBlocker } from '@okyrychenko-dev/react-action-guard-router/react-router';
+```
+
+**Approximate sizes (minified):**
+- Core utilities: ~2 KB
+- React Router adapter: ~2.5 KB
+- TanStack Router adapter: ~2.5 KB
+- Next.js adapter: ~3 KB
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm run test
+
+# Build the package
+npm run build
+
+# Type checking
+npm run typecheck
+
+# Lint
+npm run lint
+
+# Fix lint errors
+npm run lint:fix
+```
+
+---
+
+## Related Packages
+
+- [@okyrychenko-dev/react-action-guard](https://www.npmjs.com/package/@okyrychenko-dev/react-action-guard) - Core UI blocking library
+- [@okyrychenko-dev/react-action-guard-tanstack](https://www.npmjs.com/package/@okyrychenko-dev/react-action-guard-tanstack) - TanStack Query integration
+- [@okyrychenko-dev/react-action-guard-devtools](https://www.npmjs.com/package/@okyrychenko-dev/react-action-guard-devtools) - DevTools extension
+
+---
+
+## Contributing
+
+Contributions are welcome! Please ensure:
+
+1. Tests pass (`npm run test:run`)
+2. Code is properly typed (`npm run typecheck`)
+3. Linting passes (`npm run lint`)
+4. Code is formatted (`npm run format`)
+
+---
+
+## License
+
+MIT © [Oleksii Kyrychenko](https://github.com/okyrychenko-dev)

package/dist/index.cjs

@@ -0,0 +1,91 @@
+'use strict';
+
+var react = require('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) {
+  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 useDialogState() {
+  const [dialogState, setDialogState] = react.useState(null);
+  const resolveRef = react.useRef(null);
+  const confirm = react.useCallback((message) => {
+    return new Promise((resolve) => {
+      if (resolveRef.current) {
+        resolveRef.current(false);
+      }
+      resolveRef.current = resolve;
+      setDialogState({
+        isOpen: true,
+        message,
+        resolve
+      });
+    });
+  }, []);
+  const closeDialog = react.useCallback((confirmed) => {
+    const resolve = resolveRef.current;
+    if (resolve) {
+      resolve(confirmed);
+    }
+    resolveRef.current = null;
+    setDialogState(null);
+  }, []);
+  const onConfirm = react.useCallback(() => {
+    closeDialog(true);
+  }, [closeDialog]);
+  const onCancel = react.useCallback(() => {
+    closeDialog(false);
+  }, [closeDialog]);
+  return {
+    dialogState,
+    confirm,
+    onConfirm,
+    onCancel
+  };
+}
+
+exports.createBlockerId = createBlockerId;
+exports.isDefined = isDefined;
+exports.normalizeScope = normalizeScope;
+exports.resolveCondition = resolveCondition;
+exports.useBeforeUnload = useBeforeUnload;
+exports.useDialogState = useDialogState;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/utils.ts","../src/core/useBeforeUnload.ts","../src/core/useDialogState.ts"],"names":["useEffect","useState","useRef","useCallback"],"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 { 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"]}