@okyrychenko-dev/react-action-guard 0.4.0 → 0.6.0

package/README.md

@@ -53,7 +53,7 @@ function MyComponent() {
 
 ## Documentation
 
-📚 **[Interactive Storybook Documentation](https://your-storybook-url.com)** - Explore live examples and detailed guides for all hooks
+📚 **Interactive Storybook Documentation** - Run locally to explore live examples and detailed guides for all hooks
 
 To run Storybook locally:
 
@@ -154,10 +154,12 @@ Gets detailed information about all active blockers for a specific scope.
 **BlockerInfo:**
 
 - `id: string` - Unique identifier of the blocker
-- `reason?: string` - Reason for blocking
-- `priority: number` - Priority level (0-100)
+- `reason: string` - Reason for blocking (defaults to "Unknown")
+- `priority: number` - Priority level (higher = higher priority, minimum value is 0)
 - `scope: string | string[]` - Scope(s) being blocked
-- `timestamp: number` - When the blocker was added
+- `timestamp: number` - When the blocker was added (milliseconds since epoch)
+- `timeout?: number` - Optional timeout duration in milliseconds
+- `onTimeout?: (blockerId: string) => void` - Optional callback when timeout expires
 
 **Example:**
 
@@ -225,49 +227,66 @@ function ApiComponent() {
 }
 ```
 
-#### `useConfirmableBlocker(blockerId, config, options)`
+#### `useConfirmableBlocker(blockerId, config)`
 
-Creates a blocker that requires user confirmation before being removed.
+Creates a confirmable action with UI blocking while the dialog is open or the action is running.
 
 **Parameters:**
 
 - `blockerId: string` - Unique identifier for the blocker
-- `config: BlockerConfig` - Configuration object
-- `options: ConfirmableBlockerOptions`
-  - `enabled?: boolean` - Whether the blocker is active (default: true)
-  - `confirmMessage?: string` - Message to show in confirmation dialog
-  - `onConfirm?: () => void | Promise<void>` - Callback when user confirms
+- `config: ConfirmableBlockerConfig` - Configuration object
+  - `confirmMessage: string` - Message to show in confirmation dialog
+  - `confirmTitle?: string` - Dialog title (default: "Confirm Action")
+  - `confirmButtonText?: string` - Confirm button label (default: "Confirm")
+  - `cancelButtonText?: string` - Cancel button label (default: "Cancel")
+  - `onConfirm: () => void | Promise<void>` - Callback when user confirms
+  - `onCancel?: () => void` - Callback when user cancels
+  - Plus all `BlockerConfig` properties (scope, reason, priority, timeout)
 
 **Returns:**
 
-- `isBlocking: boolean` - Whether the blocker is currently active
-- `cancel: () => void` - Manually remove the blocker without confirmation
-- `requestRemoval: () => Promise<boolean>` - Request removal with confirmation
+- `execute: () => void` - Opens the confirmation dialog
+- `isDialogOpen: boolean` - Whether the dialog is open
+- `isExecuting: boolean` - Whether the confirm action is running
+- `confirmConfig: { title, message, confirmText, cancelText }` - UI-ready dialog config
+- `onConfirm: () => Promise<void>` - Confirm handler to wire to your dialog
+- `onCancel: () => void` - Cancel handler to wire to your dialog
 
 **Example:**
 
 ```jsx
-function UnsavedChangesGuard({ hasUnsavedChanges, discardChanges }) {
-  const { isBlocking, requestRemoval } = useConfirmableBlocker(
-    "unsaved-changes",
-    {
-      scope: "navigation",
-      reason: "Unsaved changes",
+function UnsavedChangesGuard({ discardChanges }) {
+  const {
+    execute,
+    isDialogOpen,
+    isExecuting,
+    confirmConfig,
+    onConfirm,
+    onCancel,
+  } = useConfirmableBlocker("unsaved-changes", {
+    scope: "navigation",
+    reason: "Unsaved changes",
+    confirmMessage: "You have unsaved changes. Are you sure you want to leave?",
+    onConfirm: async () => {
+      await discardChanges();
     },
-    {
-      enabled: hasUnsavedChanges,
-      confirmMessage: "You have unsaved changes. Are you sure you want to leave?",
-      onConfirm: async () => {
-        await discardChanges();
-      },
-    }
-  );
+  });
 
   return (
-    <div>
-      {isBlocking && <UnsavedIndicator />}
-      <button onClick={requestRemoval}>Leave</button>
-    </div>
+    <>
+      <button onClick={execute}>Leave</button>
+      {isDialogOpen && (
+        <ConfirmDialog
+          title={confirmConfig.title}
+          message={confirmConfig.message}
+          confirmText={confirmConfig.confirmText}
+          cancelText={confirmConfig.cancelText}
+          onConfirm={onConfirm}
+          onCancel={onCancel}
+        />
+      )}
+      {isExecuting && <LoadingOverlay message="Processing..." />}
+    </>
   );
 }
 ```
@@ -411,17 +430,25 @@ function MicroFrontend() {
 
 #### `useUIBlockingStore`
 
-Direct access to the Zustand store for advanced use cases.
+Direct access to the Zustand store for advanced use cases (requires a selector).
 
 **Methods:**
 
-- `addBlocker(id, config)` - Manually add a blocker
+- `addBlocker(id, config)` - Manually add a blocker (re-adding with the same ID replaces config)
+- `updateBlocker(id, config)` - Update blocker metadata (timeout restarts if new `timeout` value provided)
 - `removeBlocker(id)` - Manually remove a blocker
-- `updateBlocker(id, config)` - Update an existing blocker
 - `isBlocked(scope)` - Check if scope is blocked
 - `getBlockingInfo(scope)` - Get detailed blocking information
-- `clearAllBlockers()` - Remove all blockers
-- `clearBlockersForScope(scope)` - Remove blockers for specific scope
+- `clearAllBlockers()` - Remove all blockers (emits `"clear"` middleware event)
+- `clearBlockersForScope(scope)` - Remove blockers for specific scope (emits `"clear_scope"` middleware event)
+- `registerMiddleware(name, middleware)` - Register middleware manually
+- `unregisterMiddleware(name)` - Unregister middleware manually
+
+**Note about `updateBlocker` and timeouts:**
+- If you pass a **new** `timeout` value, the timer will be **restarted**
+- If you **don't** pass `timeout`, the existing timer continues unchanged
+- Set `timeout: 0` to **clear** an existing timeout
+- `addBlocker` always resets/creates a new timeout timer when called with the same ID
 
 **Example:**
 
@@ -429,7 +456,11 @@ Direct access to the Zustand store for advanced use cases.
 import { useUIBlockingStore } from "@okyrychenko-dev/react-action-guard";
 
 function AdvancedComponent() {
-  const { addBlocker, removeBlocker, updateBlocker } = useUIBlockingStore();
+  const { addBlocker, updateBlocker, removeBlocker } = useUIBlockingStore((state) => ({
+    addBlocker: state.addBlocker,
+    updateBlocker: state.updateBlocker,
+    removeBlocker: state.removeBlocker,
+  }));
 
   const startBlocking = () => {
     addBlocker("custom-blocker", {
@@ -440,9 +471,13 @@ function AdvancedComponent() {
   };
 
   const updatePriority = () => {
-    updateBlocker("custom-blocker", {
-      priority: 200,
-    });
+    // Update metadata - timeout continues if not changed
+    updateBlocker("custom-blocker", { priority: 200 });
+  };
+
+  const extendTimeout = () => {
+    // Update timeout - timer restarts with new value
+    updateBlocker("custom-blocker", { timeout: 60000 });
   };
 
   const stopBlocking = () => {
@@ -459,10 +494,54 @@ function AdvancedComponent() {
 }
 ```
 
+For non-hook contexts (tests, utilities, event handlers), use `uiBlockingStoreApi`:
+
+```jsx
+import { uiBlockingStoreApi } from "@okyrychenko-dev/react-action-guard";
+
+uiBlockingStoreApi.getState().addBlocker("server-call", {
+  scope: "global",
+  reason: "Server call running",
+});
+```
+
+### Store Toolkit Helpers
+
+Advanced store helpers are re-exported from the internal toolkit for custom setups:
+
+- `createShallowStore`
+- `createStoreToolkit`
+- `createStoreProvider`
+- `createResolvedStoreHooks`
+
 ## Middleware System
 
 The library includes a powerful middleware system that allows you to hook into blocker lifecycle events for analytics, logging, and performance monitoring.
 
+### Middleware Actions
+
+Middleware receives events for the following actions:
+
+- `"add"` - Blocker was added
+- `"update"` - Blocker metadata was updated
+- `"remove"` - Blocker was removed
+- `"timeout"` - Blocker was auto-removed due to timeout
+- `"clear"` - All blockers were cleared (includes `count` field)
+- `"clear_scope"` - Blockers for specific scope were cleared (includes `scope` and `count` fields)
+
+**MiddlewareContext type:**
+```typescript
+{
+  action: "add" | "update" | "remove" | "timeout" | "clear" | "clear_scope";
+  blockerId: string;
+  config?: BlockerConfig;
+  timestamp: number;
+  prevState?: BlockerConfig;  // Available for "update" and "remove"
+  scope?: string;             // Available for "clear_scope"
+  count?: number;             // Available for "clear" and "clear_scope"
+}
+```
+
 ### Built-in Middleware
 
 #### Analytics Middleware
@@ -524,6 +603,8 @@ configureMiddleware([
 ]);
 ```
 
+Note: `configureMiddleware` registers middleware on the global store. If you use `UIBlockingProvider`, register middleware via the provider's `middlewares` prop instead.
+
 ### Custom Middleware
 
 Create your own middleware to handle blocker events:
@@ -532,14 +613,20 @@ Create your own middleware to handle blocker events:
 import { configureMiddleware } from "@okyrychenko-dev/react-action-guard";
 
 const myCustomMiddleware = (context) => {
-  const { action, blockerId, config, timestamp } = context;
+  const { action, blockerId, config, timestamp, scope, count } = context;
 
   if (action === "add") {
     console.log(`Blocker added: ${blockerId}`, config);
-  } else if (action === "remove") {
-    console.log(`Blocker removed: ${blockerId}`);
   } else if (action === "update") {
     console.log(`Blocker updated: ${blockerId}`, config);
+  } else if (action === "remove") {
+    console.log(`Blocker removed: ${blockerId}`);
+  } else if (action === "timeout") {
+    console.log(`Blocker timed out: ${blockerId}`);
+  } else if (action === "clear") {
+    console.log(`All blockers cleared (${count} total)`);
+  } else if (action === "clear_scope") {
+    console.log(`Cleared ${count} blocker(s) for scope: ${scope}`);
   }
 };
 
@@ -599,23 +686,48 @@ import type {
   // Core types
   BlockerConfig,
   BlockerInfo,
-  UIBlockingState,
+  UIBlockingStore,
+  UIBlockingStoreState,
 
   // Hook types
-  ConfirmableBlockerOptions,
+  ConfirmableBlockerConfig,
+  ConfirmDialogConfig,
+  UseConfirmableBlockerReturn,
   ScheduledBlockerConfig,
   ConditionalBlockerConfig,
   BlockingSchedule,
+  UseAsyncActionOptions,
 
   // Middleware types
   Middleware,
   MiddlewareContext,
   AnalyticsConfig,
   AnalyticsProvider,
-  PerformanceMiddlewareConfig,
+  PerformanceConfig,
+
+  // Type-safe scopes
+  BlockerConfigTyped,
+  DefaultScopes,
+  ScopeValue,
 } from "@okyrychenko-dev/react-action-guard";
 ```
 
+## Type-Safe Scopes
+
+Create typed versions of the hooks to prevent scope typos at compile time:
+
+```typescript
+import { createTypedHooks } from "@okyrychenko-dev/react-action-guard";
+
+type AppScopes = "global" | "form" | "navigation" | "checkout";
+
+const { useBlocker, useIsBlocked, useAsyncAction, useBlockingInfo } =
+  createTypedHooks<AppScopes>();
+
+useBlocker("save", { scope: "form" }); // OK
+useBlocker("save", { scope: "typo" }); // Type error
+```
+
 ## Use Cases
 
 ### Loading States
@@ -670,22 +782,22 @@ function FormWithUnsavedWarning() {
   const [formData, setFormData] = useState({});
   const [hasChanges, setHasChanges] = useState(false);
 
-  const { requestRemoval } = useConfirmableBlocker(
-    "unsaved-form",
-    {
-      scope: "navigation",
-      reason: "Unsaved form data",
-      priority: 100,
+  const {
+    execute,
+    isDialogOpen,
+    confirmConfig,
+    onConfirm,
+    onCancel,
+  } = useConfirmableBlocker("unsaved-form", {
+    scope: "navigation",
+    reason: "Unsaved form data",
+    priority: 100,
+    confirmMessage: "You have unsaved changes. Discard them?",
+    onConfirm: () => {
+      setFormData({});
+      setHasChanges(false);
     },
-    {
-      enabled: hasChanges,
-      confirmMessage: "You have unsaved changes. Discard them?",
-      onConfirm: () => {
-        setFormData({});
-        setHasChanges(false);
-      },
-    }
-  );
+  });
 
   return (
     <form>
@@ -695,7 +807,17 @@ function FormWithUnsavedWarning() {
           setHasChanges(true);
         }}
       />
-      <button onClick={requestRemoval}>Cancel</button>
+      <button type="button" onClick={execute}>Cancel</button>
+      {isDialogOpen && (
+        <ConfirmDialog
+          title={confirmConfig.title}
+          message={confirmConfig.message}
+          confirmText={confirmConfig.confirmText}
+          cancelText={confirmConfig.cancelText}
+          onConfirm={onConfirm}
+          onCancel={onCancel}
+        />
+      )}
     </form>
   );
 }
@@ -804,6 +926,97 @@ function StorageQuotaGuard() {
 }
 ```
 
+### Clearing Blockers on Navigation
+
+Clear blockers when navigating away or on specific events:
+
+```jsx
+import { useUIBlockingStore } from "@okyrychenko-dev/react-action-guard";
+import { useEffect } from "react";
+
+function CheckoutPage() {
+  const { clearBlockersForScope, clearAllBlockers } = useUIBlockingStore(
+    (state) => ({
+      clearBlockersForScope: state.clearBlockersForScope,
+      clearAllBlockers: state.clearAllBlockers,
+    })
+  );
+
+  // Clear checkout-specific blockers when leaving the page
+  useEffect(() => {
+    return () => {
+      // Clean up checkout blockers on unmount
+      clearBlockersForScope("checkout");
+    };
+  }, [clearBlockersForScope]);
+
+  const handleCancelOrder = () => {
+    // Clear all blockers when user explicitly cancels
+    clearAllBlockers();
+    navigate("/");
+  };
+
+  return (
+    <div>
+      <CheckoutForm />
+      <button onClick={handleCancelOrder}>Cancel Order</button>
+    </div>
+  );
+}
+```
+
+### Managing Session Timeouts with Dynamic Updates
+
+Extend or update blocker timeouts dynamically:
+
+```jsx
+import { useUIBlockingStore } from "@okyrychenko-dev/react-action-guard";
+
+function SessionManager() {
+  const { addBlocker, updateBlocker, removeBlocker } = useUIBlockingStore(
+    (state) => ({
+      addBlocker: state.addBlocker,
+      updateBlocker: state.updateBlocker,
+      removeBlocker: state.removeBlocker,
+    })
+  );
+
+  const startSession = () => {
+    addBlocker("session-timeout", {
+      scope: "global",
+      reason: "Session expiring soon",
+      priority: 50,
+      timeout: 300000, // 5 minutes
+      onTimeout: () => {
+        logout();
+        showNotification("Session expired");
+      },
+    });
+  };
+
+  const extendSession = () => {
+    // Extend timeout - timer restarts with new value
+    updateBlocker("session-timeout", {
+      timeout: 600000, // 10 minutes
+      reason: "Session extended",
+    });
+  };
+
+  const endSession = () => {
+    removeBlocker("session-timeout");
+    logout();
+  };
+
+  return (
+    <div>
+      <button onClick={startSession}>Start Session</button>
+      <button onClick={extendSession}>Extend Session</button>
+      <button onClick={endSession}>Logout</button>
+    </div>
+  );
+}
+```
+
 ## Development
 
 ```bash