@okyrychenko-dev/react-action-guard 0.1.0 → 0.2.1

package/README.md

@@ -20,16 +20,12 @@ npm install @okyrychenko-dev/react-action-guard zustand
 ## Quick Start
 
 ```jsx
-import { useBlocker, useIsBlocked } from '@okyrychenko-dev/react-action-guard';
+import { useBlocker, useIsBlocked } from "@okyrychenko-dev/react-action-guard";
 
 function MyComponent() {
-  const isBlocked = useIsBlocked('my-scope');
+  const isBlocked = useIsBlocked("my-scope");
 
-  return (
-    <button disabled={isBlocked}>
-      Click me
-    </button>
-  );
+  return <button disabled={isBlocked}>Click me</button>;
 }
 ```
 
@@ -42,6 +38,7 @@ function MyComponent() {
 Automatically adds a blocker when the component mounts and removes it on unmount.
 
 **Parameters:**
+
 - `blockerId: string` - Unique identifier for the blocker
 - `config: BlockerConfig` - Configuration object
   - `scope?: string | string[]` - Scope(s) to block (default: "global")
@@ -53,10 +50,10 @@ Automatically adds a blocker when the component mounts and removes it on unmount
 
 ```jsx
 function MyComponent() {
-  useBlocker('my-blocker', {
-    scope: 'form',
-    reason: 'Form is saving',
-    priority: 10
+  useBlocker("my-blocker", {
+    scope: "form",
+    reason: "Form is saving",
+    priority: 10,
   });
 
   return <div>Content</div>;
@@ -68,6 +65,7 @@ function MyComponent() {
 Checks if a specific scope (or scopes) is currently blocked.
 
 **Parameters:**
+
 - `scope?: string | string[]` - Scope(s) to check (default: "global")
 
 **Returns:** `boolean` - Whether the scope is blocked
@@ -76,13 +74,9 @@ Checks if a specific scope (or scopes) is currently blocked.
 
 ```jsx
 function SubmitButton() {
-  const isFormBlocked = useIsBlocked('form');
+  const isFormBlocked = useIsBlocked("form");
 
-  return (
-    <button disabled={isFormBlocked}>
-      Submit
-    </button>
-  );
+  return <button disabled={isFormBlocked}>Submit</button>;
 }
 ```
 
@@ -91,6 +85,7 @@ function SubmitButton() {
 Wraps an async function with automatic blocking/unblocking.
 
 **Parameters:**
+
 - `actionId: string` - Identifier for the action
 - `scope?: string | string[]` - Scope(s) to block during execution
 
@@ -100,7 +95,7 @@ Wraps an async function with automatic blocking/unblocking.
 
 ```jsx
 function MyComponent() {
-  const executeWithBlocking = useAsyncAction('save-data', 'form');
+  const executeWithBlocking = useAsyncAction("save-data", "form");
 
   const handleSave = async () => {
     await executeWithBlocking(async () => {
@@ -119,6 +114,7 @@ function MyComponent() {
 Direct access to the Zustand store for advanced use cases.
 
 **Methods:**
+
 - `addBlocker(id, config)` - Manually add a blocker
 - `removeBlocker(id)` - Manually remove a blocker
 - `isBlocked(scope)` - Check if scope is blocked
@@ -129,21 +125,21 @@ Direct access to the Zustand store for advanced use cases.
 **Example:**
 
 ```jsx
-import { useUIBlockingStore } from '@okyrychenko-dev/react-action-guard';
+import { useUIBlockingStore } from "@okyrychenko-dev/react-action-guard";
 
 function AdvancedComponent() {
   const { addBlocker, removeBlocker } = useUIBlockingStore();
 
   const startBlocking = () => {
-    addBlocker('custom-blocker', {
-      scope: ['form', 'navigation'],
-      reason: 'Critical operation in progress',
-      priority: 100
+    addBlocker("custom-blocker", {
+      scope: ["form", "navigation"],
+      reason: "Critical operation in progress",
+      priority: 100,
     });
   };
 
   const stopBlocking = () => {
-    removeBlocker('custom-blocker');
+    removeBlocker("custom-blocker");
   };
 
   return (
@@ -160,11 +156,7 @@ function AdvancedComponent() {
 The package is written in TypeScript and includes full type definitions.
 
 ```typescript
-import type {
-  BlockerConfig,
-  BlockerInfo,
-  UIBlockingState
-} from '@okyrychenko-dev/react-action-guard';
+import type { BlockerConfig, BlockerInfo, UIBlockingState } from "@okyrychenko-dev/react-action-guard";
 ```
 
 ## Use Cases
@@ -175,10 +167,14 @@ import type {
 function DataLoader() {
   const [isLoading, setIsLoading] = useState(false);
 
-  useBlocker('data-loader', {
-    scope: 'content',
-    reason: 'Loading data'
-  }, isLoading);
+  useBlocker(
+    "data-loader",
+    {
+      scope: "content",
+      reason: "Loading data",
+    },
+    isLoading
+  );
 
   // ... rest of component
 }
@@ -188,8 +184,8 @@ function DataLoader() {
 
 ```jsx
 function UserForm() {
-  const executeWithBlocking = useAsyncAction('submit-form', 'form');
-  const isBlocked = useIsBlocked('form');
+  const executeWithBlocking = useAsyncAction("submit-form", "form");
+  const isBlocked = useIsBlocked("form");
 
   const handleSubmit = async (data) => {
     await executeWithBlocking(async () => {
@@ -210,7 +206,7 @@ function UserForm() {
 
 ```jsx
 function App() {
-  const isGloballyBlocked = useIsBlocked('global');
+  const isGloballyBlocked = useIsBlocked("global");
 
   return (
     <div>
@@ -239,4 +235,4 @@ npm run dev
 
 ## License
 
-MIT © Oleksandr Kyrychenko
+MIT © Olexii Kyrychenko

package/dist/index.cjs

@@ -25,6 +25,33 @@ function normalizeScopeToArray(scope) {
 var createUIBlockingActions = (set, get) => ({
   // State
   activeBlockers: /* @__PURE__ */ new Map(),
+  middlewares: /* @__PURE__ */ new Map(),
+  registerMiddleware: (name, middleware) => {
+    set((state) => {
+      const newMiddlewares = new Map(state.middlewares);
+      newMiddlewares.set(name, middleware);
+      return { middlewares: newMiddlewares };
+    });
+    console.log(`[UIBlocking] Registered middleware: ${name}`);
+  },
+  unregisterMiddleware: (name) => {
+    set((state) => {
+      const newMiddlewares = new Map(state.middlewares);
+      newMiddlewares.delete(name);
+      return { middlewares: newMiddlewares };
+    });
+    console.log(`[UIBlocking] Unregistered middleware: ${name}`);
+  },
+  runMiddlewares: async (context) => {
+    const { middlewares } = get();
+    for (const [name, middleware] of middlewares) {
+      try {
+        await middleware(context);
+      } catch (error) {
+        console.error(`[UIBlocking] Middleware "${name}" error:`, error);
+      }
+    }
+  },
   // Actions
   /**
    * Add a blocker to the store
@@ -45,6 +72,16 @@ var createUIBlockingActions = (set, get) => ({
       newBlockers.set(id, storedBlocker);
       return { activeBlockers: newBlockers };
     });
+    void get().runMiddlewares({
+      action: "add",
+      blockerId: id,
+      config: {
+        scope: config.scope,
+        reason: config.reason,
+        priority: config.priority
+      },
+      timestamp: Date.now()
+    });
   },
   /**
    * Remove a blocker from the store
@@ -53,11 +90,21 @@ var createUIBlockingActions = (set, get) => ({
    *
    */
   removeBlocker: (id) => {
+    const prevBlocker = get().activeBlockers.get(id);
     set((state) => {
       const newBlockers = new Map(state.activeBlockers);
       newBlockers.delete(id);
       return { activeBlockers: newBlockers };
     });
+    if (prevBlocker) {
+      void get().runMiddlewares({
+        action: "remove",
+        blockerId: id,
+        config: prevBlocker,
+        timestamp: Date.now(),
+        prevState: prevBlocker
+      });
+    }
   },
   /**
    * Check if a scope is currently blocked
@@ -173,10 +220,324 @@ var useAsyncAction = (actionId, scope) => {
   );
   return executeWithBlocking;
 };
+function useConfigRef(config) {
+  const configRef = react.useRef(config);
+  react.useEffect(() => {
+    configRef.current = config;
+  }, [config]);
+  return configRef;
+}
+
+// src/hooks/useBlocker.utils.ts
+function createBlockerConfig(config) {
+  return {
+    scope: config.scope,
+    reason: config.reason,
+    priority: config.priority
+  };
+}
+
+// src/hooks/useConditionalBlocker.ts
+var useConditionalBlocker = (blockerId, config) => {
+  const { addBlocker, removeBlocker } = useUIBlockingStore();
+  const intervalRef = react.useRef(null);
+  const isBlockedRef = react.useRef(false);
+  const configRef = useConfigRef(config);
+  const checkCondition = react.useCallback(() => {
+    const currentConfig = configRef.current;
+    const shouldBlock = currentConfig.condition(currentConfig.state);
+    if (shouldBlock === isBlockedRef.current) {
+      return;
+    }
+    if (shouldBlock) {
+      addBlocker(blockerId, createBlockerConfig(currentConfig));
+      isBlockedRef.current = true;
+    } else {
+      removeBlocker(blockerId);
+      isBlockedRef.current = false;
+    }
+  }, [blockerId, addBlocker, removeBlocker, configRef]);
+  react.useEffect(() => {
+    checkCondition();
+    const interval = configRef.current.checkInterval ?? 1e3;
+    intervalRef.current = setInterval(checkCondition, interval);
+    return () => {
+      if (intervalRef.current) {
+        clearInterval(intervalRef.current);
+        intervalRef.current = null;
+      }
+      if (isBlockedRef.current) {
+        removeBlocker(blockerId);
+        isBlockedRef.current = false;
+      }
+    };
+  }, [checkCondition, blockerId, removeBlocker]);
+};
+var useConfirmableBlocker = (blockerId, config) => {
+  const [isDialogOpen, setIsDialogOpen] = react.useState(false);
+  const [isExecuting, setIsExecuting] = react.useState(false);
+  useBlocker(
+    blockerId,
+    {
+      ...config,
+      reason: config.reason ?? config.confirmMessage
+    },
+    isDialogOpen || isExecuting
+  );
+  const execute = react.useCallback(() => {
+    setIsDialogOpen(true);
+  }, []);
+  const onConfirm = react.useCallback(async () => {
+    setIsDialogOpen(false);
+    setIsExecuting(true);
+    try {
+      await config.onConfirm();
+    } catch (error) {
+      console.error("[UIBlocking] Confirmable action error:", error);
+      throw error;
+    } finally {
+      setIsExecuting(false);
+    }
+  }, [config]);
+  const onCancel = react.useCallback(() => {
+    setIsDialogOpen(false);
+    config.onCancel?.();
+  }, [config]);
+  return {
+    execute,
+    isDialogOpen,
+    isExecuting,
+    confirmConfig: {
+      title: config.confirmTitle ?? "Confirm Action",
+      message: config.confirmMessage,
+      confirmText: config.confirmButtonText ?? "Confirm",
+      cancelText: config.cancelButtonText ?? "Cancel"
+    },
+    onConfirm,
+    onCancel
+  };
+};
+var useScheduledBlocker = (blockerId, config) => {
+  const { addBlocker, removeBlocker } = useUIBlockingStore();
+  const timeoutsRef = react.useRef({});
+  const configRef = useConfigRef(config);
+  const cleanup = react.useCallback(() => {
+    if (timeoutsRef.current.start) {
+      clearTimeout(timeoutsRef.current.start);
+      timeoutsRef.current.start = void 0;
+    }
+    if (timeoutsRef.current.end) {
+      clearTimeout(timeoutsRef.current.end);
+      timeoutsRef.current.end = void 0;
+    }
+  }, []);
+  react.useEffect(() => {
+    const currentConfig = configRef.current;
+    const startTime = new Date(currentConfig.schedule.start).getTime();
+    const now = Date.now();
+    let endTime;
+    if (currentConfig.schedule.duration) {
+      endTime = startTime + currentConfig.schedule.duration;
+    } else if (currentConfig.schedule.end) {
+      endTime = new Date(currentConfig.schedule.end).getTime();
+    }
+    const scheduleEnd = (end) => {
+      const remainingTime = end - Date.now();
+      if (remainingTime > 0) {
+        timeoutsRef.current.end = setTimeout(() => {
+          removeBlocker(blockerId);
+          configRef.current.onScheduleEnd?.();
+        }, remainingTime);
+      }
+    };
+    if (startTime > now) {
+      timeoutsRef.current.start = setTimeout(() => {
+        const cfg = configRef.current;
+        addBlocker(blockerId, createBlockerConfig(cfg));
+        cfg.onScheduleStart?.();
+        if (endTime) {
+          scheduleEnd(endTime);
+        }
+      }, startTime - now);
+    } else if (endTime && endTime > now) {
+      addBlocker(blockerId, createBlockerConfig(currentConfig));
+      currentConfig.onScheduleStart?.();
+      scheduleEnd(endTime);
+    } else if (!endTime && startTime <= now) {
+      addBlocker(blockerId, createBlockerConfig(currentConfig));
+      currentConfig.onScheduleStart?.();
+    } else {
+      console.warn(`[UIBlocking] Schedule is in the past for blocker "${blockerId}"`);
+    }
+    return () => {
+      cleanup();
+      removeBlocker(blockerId);
+    };
+  }, [blockerId, addBlocker, removeBlocker, cleanup]);
+};
+
+// src/middleware/loggerMiddleware.utils.ts
+var getActionEmoji = (action) => {
+  switch (action) {
+    case "add":
+      return "\u2795";
+    case "remove":
+      return "\u2796";
+    case "update":
+      return "\u{1F504}";
+    case "cancel":
+      return "\u274C";
+    case "timeout":
+      return "\u23F1\uFE0F";
+    default:
+      return "\u2753";
+  }
+};
+var extractConfigDetails = (config) => {
+  if (!config) {
+    return {};
+  }
+  const { scope, reason, priority } = config;
+  const details = {
+    scope,
+    reason
+  };
+  if (priority !== void 0) {
+    details.priority = priority;
+  }
+  return details;
+};
+var formatLogData = (context) => {
+  const configDetails = extractConfigDetails(context.config);
+  if (context.prevState) {
+    return {
+      config: configDetails,
+      prevState: extractConfigDetails(context.prevState)
+    };
+  }
+  return configDetails;
+};
+
+// src/middleware/loggerMiddleware.ts
+var LOG_PREFIX = "[UIBlocking]";
+var loggerMiddleware = (context) => {
+  const emoji = getActionEmoji(context.action);
+  const logData = formatLogData(context);
+  console.log(LOG_PREFIX, emoji, context.blockerId, logData);
+};
+
+// src/middleware/analyticsMiddleware.utils.ts
+var capitalizeFirst = (str) => {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+};
+var buildEventData = (context) => {
+  const eventData = {
+    blocker_id: context.blockerId
+  };
+  const { scope, reason, priority } = context.config ?? {};
+  if (scope !== void 0) {
+    eventData.scope = Array.isArray(scope) ? scope.join(",") : scope;
+  }
+  if (reason !== void 0) {
+    eventData.reason = reason;
+  }
+  if (priority !== void 0) {
+    eventData.priority = priority;
+  }
+  return eventData;
+};
+var trackGoogleAnalytics = (action, eventData) => {
+  if (window.gtag) {
+    window.gtag("event", `ui_blocking_${action}`, eventData);
+  }
+};
+var trackMixpanel = (action, eventData) => {
+  if (window.mixpanel) {
+    const eventName = `UI Blocking ${action.split("_").map(capitalizeFirst).join(" ")}`;
+    window.mixpanel.track(eventName, eventData);
+  }
+};
+var trackAmplitude = (action, eventData) => {
+  if (window.amplitude) {
+    const eventName = `UI Blocking ${action.split("_").map(capitalizeFirst).join(" ")}`;
+    window.amplitude.track(eventName, eventData);
+  }
+};
+var trackCustom = (trackFn, action, eventData) => {
+  try {
+    trackFn(`ui_blocking_${action}`, eventData);
+  } catch {
+  }
+};
+
+// src/middleware/analyticsMiddleware.ts
+var trackEvent = (config, context, eventData) => {
+  if ("provider" in config) {
+    switch (config.provider) {
+      case "ga":
+        trackGoogleAnalytics(context.action, eventData);
+        return;
+      case "mixpanel":
+        trackMixpanel(context.action, eventData);
+        return;
+      case "amplitude":
+        trackAmplitude(context.action, eventData);
+        return;
+    }
+  }
+  if ("track" in config) {
+    trackCustom(config.track, context.action, eventData);
+  }
+};
+var createAnalyticsMiddleware = (config) => {
+  return (context) => {
+    const eventData = buildEventData(context);
+    trackEvent(config, context, eventData);
+  };
+};
+
+// src/middleware/performanceMiddleware.utils.ts
+var handleAddAction = (blockerId, timestamp, blockStartTimes) => {
+  blockStartTimes.set(blockerId, timestamp);
+};
+
+// src/middleware/performanceMiddleware.ts
+var DEFAULT_SLOW_BLOCK_THRESHOLD = 3e3;
+var ACTION_ADD = "add";
+var ACTION_REMOVE = "remove";
+var handleRemoveAction = (context, blockStartTimes, slowBlockThreshold, onSlowBlock) => {
+  const startTime = blockStartTimes.get(context.blockerId);
+  if (startTime === void 0) {
+    return;
+  }
+  const duration = context.timestamp - startTime;
+  blockStartTimes.delete(context.blockerId);
+  if (duration >= slowBlockThreshold) {
+    console.warn(`[UIBlocking] Slow block detected: "${context.blockerId}" took ${duration.toString()}ms`);
+    onSlowBlock?.(context.blockerId, duration);
+  }
+};
+var createPerformanceMiddleware = (config = {}) => {
+  const { slowBlockThreshold = DEFAULT_SLOW_BLOCK_THRESHOLD, onSlowBlock } = config;
+  const blockStartTimes = /* @__PURE__ */ new Map();
+  return (context) => {
+    if (context.action === ACTION_ADD) {
+      handleAddAction(context.blockerId, context.timestamp, blockStartTimes);
+    } else if (context.action === ACTION_REMOVE) {
+      handleRemoveAction(context, blockStartTimes, slowBlockThreshold, onSlowBlock);
+    }
+  };
+};
 
+exports.createAnalyticsMiddleware = createAnalyticsMiddleware;
+exports.createPerformanceMiddleware = createPerformanceMiddleware;
+exports.loggerMiddleware = loggerMiddleware;
 exports.useAsyncAction = useAsyncAction;
 exports.useBlocker = useBlocker;
+exports.useConditionalBlocker = useConditionalBlocker;
+exports.useConfirmableBlocker = useConfirmableBlocker;
 exports.useIsBlocked = useIsBlocked;
+exports.useScheduledBlocker = useScheduledBlocker;
 exports.useUIBlockingStore = useUIBlockingStore;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map