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

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Olexii Kyrychenko
+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

package/README.md

@@ -11,13 +11,15 @@
 - Priority-based blocking system
 - Scoped blocking (global, specific areas, or multiple scopes)
 - Automatic cleanup on unmount
+- **Timeout mechanism** - auto-remove blockers after specified time
+- **Provider pattern** - isolated stores for SSR, testing, and micro-frontends
 - Advanced hooks for different use cases:
   - Confirmable blockers with custom dialogs
   - Scheduled blocking for maintenance windows
   - Conditional blocking based on application state
-  - Async action wrapping
+  - Async action wrapping with timeout support
 - Advanced middleware system for analytics, logging, and performance monitoring
-- TypeScript support with full type safety
+- TypeScript support with full type safety (including optional type-safe scopes)
 - Built on Zustand for efficient state management
 - Tree-shakeable - import only what you need
 - Hooks-based API
@@ -34,8 +36,8 @@ pnpm add @okyrychenko-dev/react-action-guard zustand
 
 This package requires the following peer dependencies:
 
-- [React](https://react.dev/) ^17.0.0 || ^18.0.0
-- [Zustand](https://zustand-demo.pmnd.rs/) - State management library
+- [React](https://react.dev/) ^17.0.0 || ^18.0.0 || ^19.0.0
+- [Zustand](https://zustand-demo.pmnd.rs/) ^4.5.7 || ^5.0.0 - State management library
 
 ## Quick Start
 
@@ -74,6 +76,8 @@ Automatically adds a blocker when the component mounts and removes it on unmount
   - `scope?: string | string[]` - Scope(s) to block (default: "global")
   - `reason?: string` - Reason for blocking (for debugging)
   - `priority?: number` - Priority level (higher = more important)
+  - `timeout?: number` - Auto-remove after N milliseconds
+  - `onTimeout?: (blockerId: string) => void` - Callback when auto-removed
 - `isActive?: boolean` - Whether the blocker is active (default: true)
 
 **Example:**
@@ -88,6 +92,33 @@ function MyComponent() {
 
   return <div>Content</div>;
 }
+
+// With timeout - auto-removes after 30 seconds
+function SaveButton() {
+  const [isSaving, setIsSaving] = useState(false);
+
+  useBlocker("save-operation", {
+    scope: "form",
+    reason: "Saving...",
+    timeout: 30000,
+    onTimeout: (id) => {
+      console.warn(`Operation ${id} timed out`);
+      showNotification("Operation timed out");
+      setIsSaving(false);
+    },
+  }, isSaving);
+
+  const handleSave = async () => {
+    setIsSaving(true);
+    try {
+      await saveData();
+    } finally {
+      setIsSaving(false);
+    }
+  };
+
+  return <button onClick={handleSave} disabled={isSaving}>Save</button>;
+}
 ```
 
 #### `useIsBlocked(scope)`
@@ -110,7 +141,44 @@ function SubmitButton() {
 }
 ```
 
-#### `useAsyncAction(actionId, scope)`
+#### `useBlockingInfo(scope)`
+
+Gets detailed information about all active blockers for a specific scope.
+
+**Parameters:**
+
+- `scope?: string` - Scope to get blocking information for (default: "global")
+
+**Returns:** `ReadonlyArray<BlockerInfo>` - Array of blocker information objects, sorted by priority (highest first)
+
+**BlockerInfo:**
+
+- `id: string` - Unique identifier of the blocker
+- `reason?: string` - Reason for blocking
+- `priority: number` - Priority level (0-100)
+- `scope: string | string[]` - Scope(s) being blocked
+- `timestamp: number` - When the blocker was added
+
+**Example:**
+
+```jsx
+function CheckoutButton() {
+  const blockers = useBlockingInfo("checkout");
+
+  if (blockers.length > 0) {
+    const topBlocker = blockers[0]; // Highest priority blocker
+    return (
+      <Tooltip content={`Blocked: ${topBlocker.reason}`}>
+        <Button disabled>Checkout ({blockers.length} blockers)</Button>
+      </Tooltip>
+    );
+  }
+
+  return <Button>Checkout</Button>;
+}
+```
+
+#### `useAsyncAction(actionId, scope, options)`
 
 Wraps an async function with automatic blocking/unblocking.
 
@@ -118,6 +186,9 @@ Wraps an async function with automatic blocking/unblocking.
 
 - `actionId: string` - Identifier for the action
 - `scope?: string | string[]` - Scope(s) to block during execution
+- `options?: UseAsyncActionOptions` - Optional configuration
+  - `timeout?: number` - Auto-remove blocker after N milliseconds
+  - `onTimeout?: (blockerId: string) => void` - Callback when timed out
 
 **Returns:** `(asyncFn: () => Promise<T>) => Promise<T>` - Function wrapper
 
@@ -135,6 +206,23 @@ function MyComponent() {
 
   return <button onClick={handleSave}>Save</button>;
 }
+
+// With timeout - prevents infinite blocking if operation hangs
+function ApiComponent() {
+  const execute = useAsyncAction("api-call", "global", {
+    timeout: 60000, // 1 minute timeout
+    onTimeout: (id) => {
+      showError("Request timed out. Please try again.");
+    },
+  });
+
+  const fetchData = () => execute(async () => {
+    const response = await fetch("/api/data");
+    return response.json();
+  });
+
+  return <button onClick={fetchData}>Fetch Data</button>;
+}
 ```
 
 #### `useConfirmableBlocker(blockerId, config, options)`
@@ -159,7 +247,7 @@ Creates a blocker that requires user confirmation before being removed.
 **Example:**
 
 ```jsx
-function UnsavedChangesGuard() {
+function UnsavedChangesGuard({ hasUnsavedChanges, discardChanges }) {
   const { isBlocking, requestRemoval } = useConfirmableBlocker(
     "unsaved-changes",
     {
@@ -269,6 +357,56 @@ function NetworkStatusBlocker() {
 }
 ```
 
+### Provider (Optional)
+
+#### `UIBlockingProvider`
+
+Provides an isolated store instance for SSR, testing, or micro-frontends. Without the provider, hooks use a global store.
+
+**Props:**
+
+- `children: ReactNode` - Child components
+- `enableDevtools?: boolean` - Enable Redux DevTools (default: true in development)
+- `devtoolsName?: string` - Name for DevTools (default: "UIBlocking")
+- `middlewares?: Middleware[]` - Initial middlewares to register
+
+**Example:**
+
+```jsx
+import { UIBlockingProvider } from "@okyrychenko-dev/react-action-guard";
+
+// SSR - each request gets isolated state
+function App() {
+  return (
+    <UIBlockingProvider>
+      <MyApp />
+    </UIBlockingProvider>
+  );
+}
+
+// Testing - isolated state per test, no cleanup needed
+function renderWithProvider(ui) {
+  return render(
+    <UIBlockingProvider>{ui}</UIBlockingProvider>
+  );
+}
+
+// Micro-frontends - each app has its own blocking state
+function MicroFrontend() {
+  return (
+    <UIBlockingProvider devtoolsName="MicroApp-Blocking">
+      <MicroApp />
+    </UIBlockingProvider>
+  );
+}
+```
+
+#### Context Hooks
+
+- `useUIBlockingContext()` - Get store from context (throws if outside provider)
+- `useIsInsideUIBlockingProvider()` - Check if inside a provider
+- `useUIBlockingStoreFromContext(selector)` - Select state from context store
+
 ### Store
 
 #### `useUIBlockingStore`
@@ -332,20 +470,23 @@ The library includes a powerful middleware system that allows you to hook into b
 Track blocker events with your analytics provider (Google Analytics, Mixpanel, Amplitude, or custom).
 
 ```jsx
-import { configureMiddleware, analyticsMiddleware } from "@okyrychenko-dev/react-action-guard";
+import {
+  configureMiddleware,
+  createAnalyticsMiddleware,
+} from "@okyrychenko-dev/react-action-guard";
 
 // Google Analytics
-configureMiddleware([analyticsMiddleware({ provider: "ga" })]);
+configureMiddleware([createAnalyticsMiddleware({ provider: "ga" })]);
 
 // Mixpanel
-configureMiddleware([analyticsMiddleware({ provider: "mixpanel" })]);
+configureMiddleware([createAnalyticsMiddleware({ provider: "mixpanel" })]);
 
 // Amplitude
-configureMiddleware([analyticsMiddleware({ provider: "amplitude" })]);
+configureMiddleware([createAnalyticsMiddleware({ provider: "amplitude" })]);
 
 // Custom analytics
 configureMiddleware([
-  analyticsMiddleware({
+  createAnalyticsMiddleware({
     track: (event, data) => {
       myAnalytics.track(event, data);
     },
@@ -368,10 +509,13 @@ configureMiddleware([loggerMiddleware]);
 Monitor blocker performance and detect slow operations.
 
 ```jsx
-import { configureMiddleware, performanceMiddleware } from "@okyrychenko-dev/react-action-guard";
+import {
+  configureMiddleware,
+  createPerformanceMiddleware,
+} from "@okyrychenko-dev/react-action-guard";
 
 configureMiddleware([
-  performanceMiddleware({
+  createPerformanceMiddleware({
     onSlowBlock: (blockerId, duration) => {
       console.warn(`Blocker ${blockerId} was active for ${duration}ms`);
     },
@@ -409,15 +553,15 @@ You can combine multiple middleware for comprehensive monitoring:
 ```jsx
 import {
   configureMiddleware,
-  analyticsMiddleware,
+  createAnalyticsMiddleware,
   loggerMiddleware,
-  performanceMiddleware,
+  createPerformanceMiddleware,
 } from "@okyrychenko-dev/react-action-guard";
 
 configureMiddleware([
   loggerMiddleware,
-  analyticsMiddleware({ provider: "ga" }),
-  performanceMiddleware({
+  createAnalyticsMiddleware({ provider: "ga" }),
+  createPerformanceMiddleware({
     slowBlockThreshold: 3000,
     onSlowBlock: (blockerId, duration) => {
       // Send to error tracking service
@@ -438,7 +582,10 @@ The library is fully tree-shakeable. Import only the features you need to keep y
 import { useBlocker } from "@okyrychenko-dev/react-action-guard";
 
 // Middleware is not included unless you import it
-import { configureMiddleware, analyticsMiddleware } from "@okyrychenko-dev/react-action-guard";
+import {
+  configureMiddleware,
+  createAnalyticsMiddleware,
+} from "@okyrychenko-dev/react-action-guard";
 ```
 
 The package is configured with `"sideEffects": false`, allowing modern bundlers (Webpack, Rollup, Vite) to eliminate unused code automatically.
@@ -703,4 +850,4 @@ See [CHANGELOG.md](./CHANGELOG.md) for a detailed list of changes in each versio
 
 ## License
 
-MIT © Olexii Kyrychenko
+MIT © Oleksii Kyrychenko

package/dist/index.cjs

@@ -1,9 +1,10 @@
 'use strict';
 
 var react = require('react');
-var middleware = require('zustand/middleware');
 var zustand = require('zustand');
+var middleware = require('zustand/middleware');
 var shallow = require('zustand/shallow');
+var jsxRuntime = require('react/jsx-runtime');
 
 // src/hooks/useAsyncAction/useAsyncAction.ts
 
@@ -67,13 +68,40 @@ var createUIBlockingActions = (set, get) => ({
    *
    */
   addBlocker: (id, config = {}) => {
+    const existingBlocker = get().activeBlockers.get(id);
+    if (existingBlocker?.timeoutId) {
+      clearTimeout(existingBlocker.timeoutId);
+    }
+    let timeoutId;
+    if (config.timeout && config.timeout > 0) {
+      timeoutId = setTimeout(() => {
+        if (get().activeBlockers.has(id)) {
+          config.onTimeout?.(id);
+          void get().runMiddlewares({
+            action: "timeout",
+            blockerId: id,
+            config: {
+              scope: config.scope,
+              reason: config.reason,
+              priority: config.priority,
+              timeout: config.timeout
+            },
+            timestamp: Date.now()
+          });
+          get().removeBlocker(id);
+        }
+      }, config.timeout);
+    }
     set((state) => {
       const newBlockers = new Map(state.activeBlockers);
       const storedBlocker = {
         scope: config.scope ?? DEFAULT_SCOPE,
         reason: config.reason ?? DEFAULT_REASON,
         priority: config.priority ?? DEFAULT_PRIORITY,
-        timestamp: config.timestamp ?? Date.now()
+        timestamp: config.timestamp ?? Date.now(),
+        timeout: config.timeout,
+        timeoutId,
+        onTimeout: config.onTimeout
       };
       newBlockers.set(id, storedBlocker);
       return { activeBlockers: newBlockers };
@@ -84,7 +112,8 @@ var createUIBlockingActions = (set, get) => ({
       config: {
         scope: config.scope,
         reason: config.reason,
-        priority: config.priority
+        priority: config.priority,
+        timeout: config.timeout
       },
       timestamp: Date.now()
     });
@@ -97,6 +126,9 @@ var createUIBlockingActions = (set, get) => ({
    */
   removeBlocker: (id) => {
     const prevBlocker = get().activeBlockers.get(id);
+    if (prevBlocker?.timeoutId) {
+      clearTimeout(prevBlocker.timeoutId);
+    }
     set((state) => {
       const newBlockers = new Map(state.activeBlockers);
       newBlockers.delete(id);
@@ -155,6 +187,12 @@ var createUIBlockingActions = (set, get) => ({
    * Clear all blockers from the store
    */
   clearAllBlockers: () => {
+    const { activeBlockers } = get();
+    for (const [, blocker] of activeBlockers) {
+      if (blocker.timeoutId) {
+        clearTimeout(blocker.timeoutId);
+      }
+    }
     set({ activeBlockers: /* @__PURE__ */ new Map() });
   },
   /**
@@ -164,6 +202,13 @@ var createUIBlockingActions = (set, get) => ({
    *
    */
   clearBlockersForScope: (scope) => {
+    const { activeBlockers } = get();
+    for (const [, blocker] of activeBlockers) {
+      const blockerScopes = normalizeScopeToArray(blocker.scope);
+      if (blockerScopes.includes(scope) && blocker.timeoutId) {
+        clearTimeout(blocker.timeoutId);
+      }
+    }
     set((state) => {
       const newBlockers = /* @__PURE__ */ new Map();
       for (const [id, blocker] of state.activeBlockers) {
@@ -176,6 +221,45 @@ var createUIBlockingActions = (set, get) => ({
     });
   }
 });
+var UIBlockingContext = react.createContext(null);
+function UIBlockingProvider({
+  children,
+  enableDevtools = process.env.NODE_ENV === "development",
+  devtoolsName = "UIBlocking",
+  middlewares = []
+}) {
+  const middlewaresRef = react.useRef(middlewares);
+  const store = react.useMemo(() => {
+    const baseStore = enableDevtools ? zustand.createStore(
+      middleware.devtools(createUIBlockingActions, {
+        name: devtoolsName,
+        enabled: enableDevtools
+      })
+    ) : zustand.createStore(createUIBlockingActions);
+    middlewaresRef.current.forEach((mw, index) => {
+      baseStore.getState().registerMiddleware(`provider-middleware-${index.toString()}`, mw);
+    });
+    return baseStore;
+  }, [enableDevtools, devtoolsName]);
+  return /* @__PURE__ */ jsxRuntime.jsx(UIBlockingContext.Provider, { value: store, children });
+}
+function useUIBlockingContext() {
+  const store = react.useContext(UIBlockingContext);
+  if (!store) {
+    throw new Error(
+      "useUIBlockingContext must be used within UIBlockingProvider. Either wrap your app in <UIBlockingProvider> or use the global store via useUIBlockingStore."
+    );
+  }
+  return store;
+}
+function useIsInsideUIBlockingProvider() {
+  const store = react.useContext(UIBlockingContext);
+  return store !== null;
+}
+function useUIBlockingStoreFromContext(selector) {
+  const store = useUIBlockingContext();
+  return zustand.useStore(store, shallow.useShallow(selector));
+}
 
 // src/store/uiBlockingStore.config.ts
 var devtoolsConfig = {
@@ -186,9 +270,19 @@ var devtoolsConfig = {
 // src/store/uiBlockingStore.store.ts
 var { useStore: useUIBlockingStore, useStoreApi: uiBlockingStoreApi } = createShallowStore(middleware.devtools(createUIBlockingActions, devtoolsConfig));
 
+// src/context/useResolvedStore.ts
+function useResolvedStore() {
+  const contextStore = react.useContext(UIBlockingContext);
+  return contextStore ?? uiBlockingStoreApi;
+}
+function useResolvedStoreWithSelector(selector) {
+  const store = useResolvedStore();
+  return zustand.useStore(store, shallow.useShallow(selector));
+}
+
 // src/hooks/useAsyncAction/useAsyncAction.ts
-var useAsyncAction = (actionId, scope) => {
-  const { addBlocker, removeBlocker } = useUIBlockingStore((state) => ({
+var useAsyncAction = (actionId, scope, options) => {
+  const { addBlocker, removeBlocker } = useResolvedStoreWithSelector((state) => ({
     addBlocker: state.addBlocker,
     removeBlocker: state.removeBlocker
   }));
@@ -199,19 +293,21 @@ var useAsyncAction = (actionId, scope) => {
         addBlocker(blockerId, {
           scope,
           reason: `Executing ${actionId}`,
-          priority: ASYNC_ACTION_PRIORITY
+          priority: ASYNC_ACTION_PRIORITY,
+          timeout: options?.timeout,
+          onTimeout: options?.onTimeout
         });
         return await asyncFn();
       } finally {
         removeBlocker(blockerId);
       }
     },
-    [actionId, scope, addBlocker, removeBlocker]
+    [actionId, scope, options?.timeout, options?.onTimeout, addBlocker, removeBlocker]
   );
   return executeWithBlocking;
 };
 var useBlocker = (blockerId, config, isActive = true) => {
-  const { addBlocker, removeBlocker } = useUIBlockingStore((state) => ({
+  const { addBlocker, removeBlocker } = useResolvedStoreWithSelector((state) => ({
     addBlocker: state.addBlocker,
     removeBlocker: state.removeBlocker
   }));
@@ -234,6 +330,13 @@ function createBlockerConfig(config) {
     priority: config.priority
   };
 }
+var useBlockingInfo = (scope = DEFAULT_SCOPE) => {
+  const store = useResolvedStore();
+  const activeBlockers = zustand.useStore(store, (state) => state.activeBlockers);
+  return react.useMemo(() => {
+    return store.getState().getBlockingInfo(scope);
+  }, [activeBlockers, scope, store]);
+};
 function useConfigRef(config) {
   const configRef = react.useRef(config);
   react.useEffect(() => {
@@ -244,7 +347,7 @@ function useConfigRef(config) {
 
 // src/hooks/useConditionalBlocker/useConditionalBlocker.ts
 var useConditionalBlocker = (blockerId, config) => {
-  const { addBlocker, removeBlocker } = useUIBlockingStore((state) => ({
+  const { addBlocker, removeBlocker } = useResolvedStoreWithSelector((state) => ({
     addBlocker: state.addBlocker,
     removeBlocker: state.removeBlocker
   }));
@@ -327,7 +430,7 @@ var useConfirmableBlocker = (blockerId, config) => {
 
 // src/hooks/useIsBlocked/useIsBlocked.ts
 var useIsBlocked = (scope) => {
-  return useUIBlockingStore((state) => state.isBlocked(scope));
+  return useResolvedStoreWithSelector((state) => state.isBlocked(scope));
 };
 
 // src/hooks/useScheduledBlocker/useScheduledBlocker.utils.ts
@@ -369,7 +472,7 @@ function isScheduleInPast(startTime, endTime, now) {
 
 // src/hooks/useScheduledBlocker/useScheduledBlocker.ts
 var useScheduledBlocker = (blockerId, config) => {
-  const { addBlocker, removeBlocker } = useUIBlockingStore((state) => ({
+  const { addBlocker, removeBlocker } = useResolvedStoreWithSelector((state) => ({
     addBlocker: state.addBlocker,
     removeBlocker: state.removeBlocker
   }));
@@ -506,6 +609,15 @@ var createAnalyticsMiddleware = (config) => {
   };
 };
 
+// src/middleware/configureMiddleware.ts
+function configureMiddleware(middlewares) {
+  const store = uiBlockingStoreApi.getState();
+  middlewares.forEach((middleware, index) => {
+    const name = `middleware-${index.toString()}`;
+    store.registerMiddleware(name, middleware);
+  });
+}
+
 // src/middleware/loggerMiddleware.utils.ts
 var getActionEmoji = (action) => {
   switch (action) {
@@ -591,16 +703,39 @@ var createPerformanceMiddleware = (config = {}) => {
   };
 };
 
+// src/createTypedHooks.ts
+function createTypedHooks() {
+  return {
+    useBlocker: (blockerId, config, isActive) => {
+      useBlocker(blockerId, config, isActive);
+    },
+    useIsBlocked: (scope) => {
+      return useIsBlocked(scope);
+    },
+    useAsyncAction: (actionId, scope, options) => {
+      return useAsyncAction(actionId, scope, options);
+    },
+    useBlockingInfo: (scope) => useBlockingInfo(scope)
+  };
+}
+
+exports.UIBlockingProvider = UIBlockingProvider;
+exports.configureMiddleware = configureMiddleware;
 exports.createAnalyticsMiddleware = createAnalyticsMiddleware;
 exports.createPerformanceMiddleware = createPerformanceMiddleware;
+exports.createTypedHooks = createTypedHooks;
 exports.loggerMiddleware = loggerMiddleware;
 exports.uiBlockingStoreApi = uiBlockingStoreApi;
 exports.useAsyncAction = useAsyncAction;
 exports.useBlocker = useBlocker;
+exports.useBlockingInfo = useBlockingInfo;
 exports.useConditionalBlocker = useConditionalBlocker;
 exports.useConfirmableBlocker = useConfirmableBlocker;
 exports.useIsBlocked = useIsBlocked;
+exports.useIsInsideUIBlockingProvider = useIsInsideUIBlockingProvider;
 exports.useScheduledBlocker = useScheduledBlocker;
+exports.useUIBlockingContext = useUIBlockingContext;
 exports.useUIBlockingStore = useUIBlockingStore;
+exports.useUIBlockingStoreFromContext = useUIBlockingStoreFromContext;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map