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

package/README.md

@@ -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:**
 
@@ -433,22 +435,30 @@ Direct access to the Zustand store for advanced use cases (requires a selector).
 **Methods:**
 
 - `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
 - `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:**
 
 ```jsx
 import { useUIBlockingStore } from "@okyrychenko-dev/react-action-guard";
 
 function AdvancedComponent() {
-  const { addBlocker, removeBlocker } = useUIBlockingStore((state) => ({
+  const { addBlocker, updateBlocker, removeBlocker } = useUIBlockingStore((state) => ({
     addBlocker: state.addBlocker,
+    updateBlocker: state.updateBlocker,
     removeBlocker: state.removeBlocker,
   }));
 
@@ -461,12 +471,13 @@ function AdvancedComponent() {
   };
 
   const updatePriority = () => {
-    // Re-add with the same ID to update the config
-    addBlocker("custom-blocker", {
-      scope: ["form", "navigation"],
-      reason: "Critical operation in progress",
-      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 = () => {
@@ -507,6 +518,30 @@ Advanced store helpers are re-exported from the internal toolkit for custom setu
 
 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
@@ -570,8 +605,6 @@ configureMiddleware([
 
 Note: `configureMiddleware` registers middleware on the global store. If you use `UIBlockingProvider`, register middleware via the provider's `middlewares` prop instead.
 
-Note: Middleware action types include `update` and `cancel`, but the store currently emits `add`, `remove`, and `timeout`.
-
 ### Custom Middleware
 
 Create your own middleware to handle blocker events:
@@ -580,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}`);
   }
 };
 
@@ -887,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

package/dist/index.cjs

@@ -24,6 +24,16 @@ function normalizeScopeToArray(scope) {
 }
 
 // src/store/uiBlockingStore.actions.ts
+var normalizePriority = (priority, fallback = DEFAULT_PRIORITY) => {
+  return priority !== void 0 ? Math.max(0, priority) : fallback;
+};
+var createMiddlewareContext = (action, blockerId, config, prevState) => ({
+  action,
+  blockerId,
+  config,
+  timestamp: Date.now(),
+  ...prevState && { prevState }
+});
 var createUIBlockingActions = (set, get) => ({
   // State
   activeBlockers: /* @__PURE__ */ new Map(),
@@ -34,7 +44,6 @@ var createUIBlockingActions = (set, get) => ({
       newMiddlewares.set(name, middleware);
       return { middlewares: newMiddlewares };
     });
-    console.log(`[UIBlocking] Registered middleware: ${name}`);
   },
   unregisterMiddleware: (name) => {
     set((state) => {
@@ -42,7 +51,6 @@ var createUIBlockingActions = (set, get) => ({
       newMiddlewares.delete(name);
       return { middlewares: newMiddlewares };
     });
-    console.log(`[UIBlocking] Unregistered middleware: ${name}`);
   },
   runMiddlewares: async (context) => {
     const { middlewares } = get();
@@ -72,17 +80,14 @@ var createUIBlockingActions = (set, get) => ({
       timeoutId = setTimeout(() => {
         if (get().activeBlockers.has(id)) {
           config.onTimeout?.(id);
-          void get().runMiddlewares({
-            action: "timeout",
-            blockerId: id,
-            config: {
+          void get().runMiddlewares(
+            createMiddlewareContext("timeout", id, {
               scope: config.scope,
               reason: config.reason,
               priority: config.priority,
               timeout: config.timeout
-            },
-            timestamp: Date.now()
-          });
+            })
+          );
           get().removeBlocker(id);
         }
       }, config.timeout);
@@ -92,7 +97,7 @@ var createUIBlockingActions = (set, get) => ({
       const storedBlocker = {
         scope: config.scope ?? DEFAULT_SCOPE,
         reason: config.reason ?? DEFAULT_REASON,
-        priority: config.priority ?? DEFAULT_PRIORITY,
+        priority: normalizePriority(config.priority),
         timestamp: config.timestamp ?? Date.now(),
         timeout: config.timeout,
         timeoutId,
@@ -101,17 +106,92 @@ var createUIBlockingActions = (set, get) => ({
       newBlockers.set(id, storedBlocker);
       return { activeBlockers: newBlockers };
     });
-    void get().runMiddlewares({
-      action: "add",
-      blockerId: id,
-      config: {
+    void get().runMiddlewares(
+      createMiddlewareContext("add", id, {
         scope: config.scope,
         reason: config.reason,
         priority: config.priority,
         timeout: config.timeout
-      },
-      timestamp: Date.now()
+      })
+    );
+  },
+  /**
+   * Update blocker metadata. If timeout is updated, the timer will be restarted.
+   *
+   * @param id - Unique blocker identifier
+   * @param config - Partial blocker configuration to merge
+   *
+   */
+  updateBlocker: (id, config = {}) => {
+    const existingBlocker = get().activeBlockers.get(id);
+    if (!existingBlocker) {
+      get().addBlocker(id, config);
+      return;
+    }
+    let timeoutId = existingBlocker.timeoutId;
+    const timeoutChanged = config.timeout !== void 0 && config.timeout !== existingBlocker.timeout;
+    if (timeoutChanged) {
+      if (existingBlocker.timeoutId) {
+        clearTimeout(existingBlocker.timeoutId);
+      }
+      if (config.timeout && config.timeout > 0) {
+        const newTimeout = config.timeout;
+        const newOnTimeout = config.onTimeout ?? existingBlocker.onTimeout;
+        timeoutId = setTimeout(() => {
+          if (get().activeBlockers.has(id)) {
+            newOnTimeout?.(id);
+            void get().runMiddlewares(
+              createMiddlewareContext("timeout", id, {
+                scope: config.scope ?? existingBlocker.scope,
+                reason: config.reason ?? existingBlocker.reason,
+                priority: config.priority ?? existingBlocker.priority,
+                timeout: newTimeout
+              })
+            );
+            get().removeBlocker(id);
+          }
+        }, newTimeout);
+      } else {
+        timeoutId = void 0;
+      }
+    }
+    const updatedBlocker = {
+      ...existingBlocker,
+      scope: config.scope ?? existingBlocker.scope,
+      reason: config.reason ?? existingBlocker.reason,
+      priority: normalizePriority(config.priority, existingBlocker.priority),
+      timestamp: config.timestamp ?? existingBlocker.timestamp,
+      timeout: config.timeout ?? existingBlocker.timeout,
+      timeoutId,
+      onTimeout: config.onTimeout ?? existingBlocker.onTimeout
+    };
+    set((state) => {
+      const newBlockers = new Map(state.activeBlockers);
+      newBlockers.set(id, updatedBlocker);
+      return { activeBlockers: newBlockers };
     });
+    void get().runMiddlewares(
+      createMiddlewareContext(
+        "update",
+        id,
+        {
+          scope: updatedBlocker.scope,
+          reason: updatedBlocker.reason,
+          priority: updatedBlocker.priority,
+          timeout: updatedBlocker.timeout,
+          onTimeout: updatedBlocker.onTimeout,
+          timestamp: updatedBlocker.timestamp
+        },
+        {
+          scope: existingBlocker.scope,
+          reason: existingBlocker.reason,
+          priority: existingBlocker.priority,
+          timeout: existingBlocker.timeout,
+          onTimeout: existingBlocker.onTimeout,
+          timestamp: existingBlocker.timestamp
+        }
+      )
+    );
   },
   /**
    * Remove a blocker from the store
@@ -130,13 +210,7 @@ var createUIBlockingActions = (set, get) => ({
       return { activeBlockers: newBlockers };
     });
     if (prevBlocker) {
-      void get().runMiddlewares({
-        action: "remove",
-        blockerId: id,
-        config: prevBlocker,
-        timestamp: Date.now(),
-        prevState: prevBlocker
-      });
+      void get().runMiddlewares(createMiddlewareContext("remove", id, prevBlocker, prevBlocker));
     }
   },
   /**
@@ -183,12 +257,21 @@ var createUIBlockingActions = (set, get) => ({
    */
   clearAllBlockers: () => {
     const { activeBlockers } = get();
+    const count = activeBlockers.size;
     for (const [, blocker] of activeBlockers) {
       if (blocker.timeoutId) {
         clearTimeout(blocker.timeoutId);
       }
     }
     set({ activeBlockers: /* @__PURE__ */ new Map() });
+    if (count > 0) {
+      void get().runMiddlewares({
+        action: "clear",
+        blockerId: "*",
+        timestamp: Date.now(),
+        count
+      });
+    }
   },
   /**
    * Clear all blockers for a specific scope
@@ -198,10 +281,14 @@ var createUIBlockingActions = (set, get) => ({
    */
   clearBlockersForScope: (scope) => {
     const { activeBlockers } = get();
+    let count = 0;
     for (const [, blocker] of activeBlockers) {
       const blockerScopes = normalizeScopeToArray(blocker.scope);
-      if (blockerScopes.includes(scope) && blocker.timeoutId) {
-        clearTimeout(blocker.timeoutId);
+      if (blockerScopes.includes(scope)) {
+        if (blocker.timeoutId) {
+          clearTimeout(blocker.timeoutId);
+        }
+        count++;
       }
     }
     set((state) => {
@@ -214,6 +301,15 @@ var createUIBlockingActions = (set, get) => ({
       }
       return { activeBlockers: newBlockers };
     });
+    if (count > 0) {
+      void get().runMiddlewares({
+        action: "clear_scope",
+        blockerId: "*",
+        timestamp: Date.now(),
+        scope,
+        count
+      });
+    }
   }
 });
 var {
@@ -273,9 +369,11 @@ var useAsyncAction = (actionId, scope, options) => {
     addBlocker: state.addBlocker,
     removeBlocker: state.removeBlocker
   }));
+  const counterRef = react.useRef(0);
   const executeWithBlocking = react.useCallback(
     async (asyncFn) => {
-      const blockerId = `${actionId}-${Date.now().toString()}`;
+      counterRef.current += 1;
+      const blockerId = `${actionId}-${String(counterRef.current)}`;
       try {
         addBlocker(blockerId, {
           scope,
@@ -610,14 +708,16 @@ var getActionEmoji = (action) => {
   switch (action) {
     case "add":
       return "\u2795";
-    case "remove":
-      return "\u2796";
     case "update":
       return "\u{1F504}";
-    case "cancel":
-      return "\u274C";
+    case "remove":
+      return "\u2796";
     case "timeout":
       return "\u23F1\uFE0F";
+    case "clear":
+      return "\u{1F9F9}";
+    case "clear_scope":
+      return "\u{1F3AF}";
     default:
       return "\u2753";
   }
@@ -638,13 +738,23 @@ var extractConfigDetails = (config) => {
 };
 var formatLogData = (context) => {
   const configDetails = extractConfigDetails(context.config);
+  const logData = {};
+  if (context.scope !== void 0) {
+    logData.scope = context.scope;
+  }
+  if (context.count !== void 0) {
+    logData.count = context.count;
+  }
+  if (Object.keys(configDetails).length > 0) {
+    logData.config = configDetails;
+  }
   if (context.prevState) {
-    return {
-      config: configDetails,
-      prevState: extractConfigDetails(context.prevState)
-    };
+    logData.prevState = extractConfigDetails(context.prevState);
+  }
+  if (Object.keys(logData).length === 0) {
+    return configDetails;
   }
-  return configDetails;
+  return Object.keys(logData).length === 1 && logData.config ? configDetails : logData;
 };
 
 // src/middleware/loggerMiddleware.ts