@okyrychenko-dev/react-action-guard 0.7.0 → 1.0.1

package/README.md

@@ -4,25 +4,18 @@
 [![npm downloads](https://img.shields.io/npm/dm/@okyrychenko-dev/react-action-guard.svg)](https://www.npmjs.com/package/@okyrychenko-dev/react-action-guard)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> Elegant UI blocking management for React applications with priorities, scopes, and automatic cleanup
-
-## Features
-
-- 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 with timeout support
-- Advanced middleware system for analytics, logging, and performance monitoring
-- 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
+> Coordinate UI blocking across async actions and competing interactions in React
+
+`react-action-guard` helps you prevent duplicate submits, conflicting actions, and stale UI interactions without scattering local `isLoading` flags across components.
+
+## Why Use It
+
+- Wrap async work with `useAsyncAction` and get blocker cleanup automatically
+- Coordinate blocking by `scope` across unrelated components
+- Inspect current blockers with `useIsBlocked` and `useBlockingInfo`
+- Isolate state per provider for SSR, tests, and micro-frontends
+- Extend lifecycle events with optional middleware
+- Add advanced hooks for scheduled, confirmable, or conditional flows when needed
 
 ## Installation
 
@@ -39,18 +32,52 @@ This package requires the following peer dependencies:
 - [React](https://react.dev/) ^18.0.0 || ^19.0.0
 - [Zustand](https://zustand-demo.pmnd.rs/) ^5.0.0 - State management library
 
+## 1.0 Migration
+
+`1.0.0` removes public re-exports of internal `react-zustand-toolkit` helpers from the root package.
+
+If you previously imported `createShallowStore`, `createStoreToolkit`, `createStoreProvider`, or `createResolvedStoreHooks` from `@okyrychenko-dev/react-action-guard`, import them directly from `@okyrychenko-dev/react-zustand-toolkit` instead.
+
 ## Quick Start
 
 ```jsx
-import { useBlocker, useIsBlocked } from "@okyrychenko-dev/react-action-guard";
+import { useAsyncAction, useIsBlocked } from "@okyrychenko-dev/react-action-guard";
 
-function MyComponent() {
-  const isBlocked = useIsBlocked("my-scope");
+function SaveButton() {
+  const isSaving = useIsBlocked("form");
+  const runSave = useAsyncAction("save-profile", "form");
 
-  return <button disabled={isBlocked}>Click me</button>;
+  const handleClick = async () => {
+    await runSave(async () => {
+      await api.saveProfile();
+    });
+  };
+
+  return <button onClick={handleClick} disabled={isSaving}>Save</button>;
 }
 ```
 
+## Core Concepts
+
+- `scope` lets you coordinate blocking across components like `"form"`, `"navigation"`, or `"checkout"`
+- `useAsyncAction` is the fastest path for async workflows
+- `useBlocker` is the lower-level hook when you already have your own boolean state
+- `UIBlockingProvider` gives you isolated state instead of the default global store
+
+## Core Use Cases
+
+### Prevent duplicate async actions
+
+Use `useAsyncAction` when a button, mutation, or workflow should block while work is in flight.
+
+### Coordinate multiple components
+
+Use shared scopes when one component starts work and another component should react by disabling UI or showing blocker details.
+
+### Isolate blocking domains
+
+Use `UIBlockingProvider` when each request, test, or micro-frontend should get its own store instance.
+
 ## Documentation
 
 📚 **Interactive Storybook Documentation** - Run locally to explore live examples and detailed guides for all hooks
@@ -65,7 +92,16 @@ npm run storybook
 
 ### Hooks
 
-#### `useBlocker(blockerId, config, isActive)`
+#### Core hooks
+
+Start with these first:
+
+- `useAsyncAction`
+- `useBlocker`
+- `useIsBlocked`
+- `useBlockingInfo`
+
+#### `useBlocker(blockerId, config, isActive?)`
 
 Automatically adds a blocker when the component mounts and removes it on unmount.
 
@@ -80,6 +116,8 @@ Automatically adds a blocker when the component mounts and removes it on unmount
   - `onTimeout?: (blockerId: string) => void` - Callback when auto-removed
 - `isActive?: boolean` - Whether the blocker is active (default: true)
 
+When `isActive` is `true`, changing `config` updates the existing blocker via `updateBlocker` without requiring unmount/remount.
+
 **Example:**
 
 ```jsx
@@ -227,9 +265,18 @@ function ApiComponent() {
 }
 ```
 
+#### Advanced hooks
+
+These hooks are useful, but they are not the main onboarding path for most apps:
+
+- `useConfirmableBlocker` for confirmation flows
+- `useScheduledBlocker` for time-window blocking
+- `useConditionalBlocker` for polling-based conditional synchronization
+
 #### `useConfirmableBlocker(blockerId, config)`
 
 Creates a confirmable action with UI blocking while the dialog is open or the action is running.
+Use it for advanced confirmation flows after the core hooks are already a good fit.
 
 **Parameters:**
 
@@ -294,6 +341,7 @@ function UnsavedChangesGuard({ discardChanges }) {
 #### `useScheduledBlocker(blockerId, config)`
 
 Blocks UI during a scheduled time period or maintenance window.
+Use it when blocking is driven by time windows rather than user-triggered async work.
 
 **Parameters:**
 
@@ -334,6 +382,7 @@ function MaintenanceWindow() {
 #### `useConditionalBlocker(blockerId, config)`
 
 Periodically checks a condition and blocks/unblocks based on the result.
+Use this when polling is an acceptable tradeoff and the condition is not naturally event-driven.
 
 **Parameters:**
 
@@ -422,9 +471,17 @@ function MicroFrontend() {
 
 #### Context Hooks
 
-- `useUIBlockingContext()` - Get store from context (throws if outside provider)
+- `useUIBlockingContext()` - Get store API from context (throws if outside provider)
+- `useOptionalUIBlockingContext()` - Get store API from context or `null` outside provider
 - `useIsInsideUIBlockingProvider()` - Check if inside a provider
 - `useUIBlockingStoreFromContext(selector)` - Select state from context store
+- `useResolvedStoreApi()` - Resolve to provider store API or global store API
+- `useResolvedValue(selector)` - Resolve to provider/global store and select with shallow comparison
+
+Legacy aliases remain available for backward compatibility:
+- `useOptionalContext()` -> `useOptionalUIBlockingContext()`
+- `useResolvedStore()` -> `useResolvedStoreApi()`
+- `useResolvedStoreWithSelector()` -> `useResolvedValue()`
 
 ### Store
 
@@ -505,18 +562,11 @@ uiBlockingStoreApi.getState().addBlocker("server-call", {
 });
 ```
 
-### 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 is optional. Use it when you need analytics, logging, or performance visibility around blocker lifecycle events.
+
+Most applications can start without middleware and add it later if blocker observability becomes important.
 
 ### Middleware Actions
 
@@ -544,6 +594,8 @@ Middleware receives events for the following actions:
 
 ### Built-in Middleware
 
+These are extensions around the blocker lifecycle, not the primary onboarding path for the library.
+
 #### Analytics Middleware
 
 Track blocker events with your analytics provider (Google Analytics, Mixpanel, Amplitude, or custom).
@@ -604,6 +656,9 @@ configureMiddleware([
 ```
 
 Note: `configureMiddleware` registers middleware on the global store. If you use `UIBlockingProvider`, register middleware via the provider's `middlewares` prop instead.
+Each `configureMiddleware(...)` call replaces previously configured global middlewares (`middleware-*`) and keeps provider-level middlewares untouched.
+
+Analytics middleware is SSR-safe: in non-browser environments it becomes a no-op for `ga`, `mixpanel`, and `amplitude` providers.
 
 ### Custom Middleware
 
@@ -635,7 +690,7 @@ configureMiddleware([myCustomMiddleware]);
 
 ### Combining Middleware
 
-You can combine multiple middleware for comprehensive monitoring:
+You can combine multiple middleware when you need broader observability:
 
 ```jsx
 import {
@@ -730,6 +785,8 @@ useBlocker("save", { scope: "typo" }); // Type error
 
 ## Use Cases
 
+The first four examples below are the most representative starting points.
+
 ### Loading States
 
 ```jsx
@@ -773,7 +830,7 @@ function UserForm() {
 }
 ```
 
-### Unsaved Changes Protection
+### Advanced: Unsaved Changes Protection
 
 ```jsx
 import { useConfirmableBlocker } from "@okyrychenko-dev/react-action-guard";
@@ -870,7 +927,7 @@ function MultiStepWizard() {
 }
 ```
 
-### Scheduled Maintenance Window
+### Advanced: Scheduled Maintenance Window
 
 ```jsx
 import { useScheduledBlocker } from "@okyrychenko-dev/react-action-guard";
@@ -897,7 +954,7 @@ function App() {
 }
 ```
 
-### Dynamic Blocking Based on State
+### Advanced: Dynamic Blocking Based on State
 
 ```jsx
 import { useConditionalBlocker } from "@okyrychenko-dev/react-action-guard";

package/dist/index.cjs

@@ -1,14 +1,14 @@
 'use strict';
 
-var react = require('react');
 var reactZustandToolkit = require('@okyrychenko-dev/react-zustand-toolkit');
 var zustand = require('zustand');
 require('zustand/react/shallow');
 var jsxRuntime = require('react/jsx-runtime');
 var shallow = require('zustand/shallow');
 var middleware = require('zustand/middleware');
+var react = require('react');
 
-// src/hooks/useAsyncAction/useAsyncAction.ts
+// src/context/UIBlockingContext.tsx
 
 // src/store/uiBlockingStore.constants.ts
 var DEFAULT_SCOPE = "global";
@@ -56,11 +56,10 @@ var createUIBlockingActions = (set, get) => ({
   },
   runMiddlewares: async (context) => {
     const { middlewares } = get();
-    for (const [name, middleware] of middlewares) {
+    for (const [, middleware] of middlewares) {
       try {
         await middleware(context);
-      } catch (error) {
-        console.error(`[UIBlocking] Middleware "${name}" error:`, error);
+      } catch {
       }
     }
   },
@@ -354,7 +353,8 @@ var createUIBlockingActions = (set, get) => ({
     for (const [id, blocker] of activeBlockers) {
       const blockerScopes = normalizeScopeToArray(blocker.scope);
       if (blocker.scope === DEFAULT_SCOPE || blockerScopes.includes(scope)) {
-        blockers.push({ id, ...blocker });
+        const { timeoutId: _timeoutId, ...publicBlocker } = blocker;
+        blockers.push({ id, ...publicBlocker });
       }
     }
     return blockers.sort((a, b) => b.priority - a.priority);
@@ -450,18 +450,24 @@ var createUIBlockingActions = (set, get) => ({
 });
 var {
   Provider: BaseUIBlockingProvider,
-  useContext: useUIBlockingContext,
-  useContextStore: useUIBlockingStoreFromContext,
+  useContextStoreApi: useUIBlockingContext,
+  useContextStore: baseUseUIBlockingStoreFromContext,
   useIsInsideProvider: useIsInsideUIBlockingProvider,
-  useOptionalContext
+  useContextStoreOptional: useOptionalUIBlockingContext
 } = reactZustandToolkit.createStoreProvider(createUIBlockingActions, "UIBlocking");
+function useUIBlockingStoreFromContext(selector, equalityFn) {
+  if (selector) {
+    return baseUseUIBlockingStoreFromContext(selector, equalityFn);
+  }
+  return baseUseUIBlockingStoreFromContext();
+}
 function UIBlockingProvider({
   children,
   enableDevtools = process.env.NODE_ENV === "development",
   devtoolsName = "UIBlocking",
   middlewares = []
 }) {
-  const handleStoreCreate = (store) => {
+  const handleStoreInit = (store) => {
     middlewares.forEach((mw, index) => {
       store.getState().registerMiddleware(`provider-middleware-${index.toString()}`, mw);
     });
@@ -471,7 +477,7 @@ function UIBlockingProvider({
     {
       enableDevtools,
       devtoolsName,
-      onStoreCreate: handleStoreCreate,
+      onStoreInit: handleStoreInit,
       children
     }
   );
@@ -484,24 +490,31 @@ var devtoolsConfig = {
 };
 
 // src/store/uiBlockingStore.store.ts
-var { useStore: useUIBlockingStore, useStoreApi: uiBlockingStoreApi } = reactZustandToolkit.createShallowStore(middleware.devtools(createUIBlockingActions, devtoolsConfig));
+var storeBindings = reactZustandToolkit.createShallowStore(
+  middleware.devtools(createUIBlockingActions, devtoolsConfig)
+);
+var uiBlockingStoreApi = storeBindings.useStoreApi;
+function useUIBlockingStore(selector, equalityFn) {
+  if (selector) {
+    return storeBindings.useStore(selector, equalityFn);
+  }
+  return storeBindings.useStore();
+}
 
 // src/context/useResolvedStore.ts
 function useOptionalContextStore() {
-  return useOptionalContext();
+  return useOptionalUIBlockingContext();
 }
-function useResolvedStore() {
+function useResolvedStoreApi() {
   const contextStore = useOptionalContextStore();
   return contextStore ?? uiBlockingStoreApi;
 }
-function useResolvedStoreWithSelector(selector) {
-  const store = useResolvedStore();
+function useResolvedValue(selector) {
+  const store = useResolvedStoreApi();
   return zustand.useStore(store, shallow.useShallow(selector));
 }
-
-// src/hooks/useAsyncAction/useAsyncAction.ts
 function useAsyncAction(actionId, scope, options) {
-  const { addBlocker, removeBlocker } = useResolvedStoreWithSelector((state) => ({
+  const { addBlocker, removeBlocker } = useResolvedValue((state) => ({
     addBlocker: state.addBlocker,
     removeBlocker: state.removeBlocker
   }));
@@ -528,19 +541,33 @@ function useAsyncAction(actionId, scope, options) {
   return executeWithBlocking;
 }
 function useBlocker(blockerId, config, isActive = true) {
-  const { addBlocker, removeBlocker } = useResolvedStoreWithSelector((state) => ({
+  const { addBlocker, removeBlocker, updateBlocker } = useResolvedValue((state) => ({
     addBlocker: state.addBlocker,
-    removeBlocker: state.removeBlocker
+    removeBlocker: state.removeBlocker,
+    updateBlocker: state.updateBlocker
   }));
+  const lastConfigRef = react.useRef(null);
   react.useEffect(() => {
     if (!isActive || !blockerId) {
       return;
     }
     addBlocker(blockerId, config);
+    lastConfigRef.current = config;
     return () => {
+      lastConfigRef.current = null;
       removeBlocker(blockerId);
     };
   }, [blockerId, isActive, addBlocker, removeBlocker]);
+  react.useEffect(() => {
+    if (!isActive || !blockerId) {
+      return;
+    }
+    if (lastConfigRef.current === config) {
+      return;
+    }
+    updateBlocker(blockerId, config);
+    lastConfigRef.current = config;
+  }, [blockerId, config, isActive, updateBlocker]);
 }
 
 // src/hooks/useBlocker/useBlocker.utils.ts
@@ -552,7 +579,7 @@ function createBlockerConfig(config) {
   };
 }
 function useBlockingInfo(scope = DEFAULT_SCOPE) {
-  const store = useResolvedStore();
+  const store = useResolvedStoreApi();
   const activeBlockers = zustand.useStore(store, (state) => state.activeBlockers);
   return react.useMemo(() => {
     return store.getState().getBlockingInfo(scope);
@@ -568,7 +595,7 @@ function useConfigRef(config) {
 
 // src/hooks/useConditionalBlocker/useConditionalBlocker.ts
 function useConditionalBlocker(blockerId, config) {
-  const { addBlocker, removeBlocker } = useResolvedStoreWithSelector((state) => ({
+  const { addBlocker, removeBlocker } = useResolvedValue((state) => ({
     addBlocker: state.addBlocker,
     removeBlocker: state.removeBlocker
   }));
@@ -623,9 +650,6 @@ function useConfirmableBlocker(blockerId, config) {
     setIsExecuting(true);
     try {
       await config.onConfirm();
-    } catch (error) {
-      console.error("[UIBlocking] Confirmable action error:", error);
-      throw error;
     } finally {
       setIsExecuting(false);
     }
@@ -651,7 +675,7 @@ function useConfirmableBlocker(blockerId, config) {
 
 // src/hooks/useIsBlocked/useIsBlocked.ts
 function useIsBlocked(scope) {
-  return useResolvedStoreWithSelector((state) => state.isBlocked(scope));
+  return useResolvedValue((state) => state.isBlocked(scope));
 }
 
 // src/hooks/useScheduledBlocker/useScheduledBlocker.utils.ts
@@ -693,7 +717,7 @@ function isScheduleInPast(startTime, endTime, now) {
 
 // src/hooks/useScheduledBlocker/useScheduledBlocker.ts
 function useScheduledBlocker(blockerId, config) {
-  const { addBlocker, removeBlocker } = useResolvedStoreWithSelector((state) => ({
+  const { addBlocker, removeBlocker } = useResolvedValue((state) => ({
     addBlocker: state.addBlocker,
     removeBlocker: state.removeBlocker
   }));
@@ -714,7 +738,6 @@ function useScheduledBlocker(blockerId, config) {
     const startTime = parseDate(currentConfig.schedule.start);
     const now = Date.now();
     if (!isValidTimestamp(startTime)) {
-      console.error(`[UIBlocking] Invalid start time for blocker "${blockerId}"`);
       return;
     }
     const scheduleEnd = () => {
@@ -739,9 +762,6 @@ function useScheduledBlocker(blockerId, config) {
     if (startTime > now) {
       const delay = startTime - now;
       if (!isSafeTimeout(delay)) {
-        console.warn(
-          `[UIBlocking] Schedule delay exceeds maximum timeout (${MAX_TIMEOUT_MS.toString()}ms) for blocker "${blockerId}"`
-        );
         return;
       }
       timeoutsRef.current.start = setTimeout(startBlocking, delay);
@@ -750,7 +770,7 @@ function useScheduledBlocker(blockerId, config) {
       if (isInBlockingPeriod(startTime, endTime, now)) {
         startBlocking();
       } else if (isScheduleInPast(startTime, endTime, now)) {
-        console.warn(`[UIBlocking] Schedule is in the past for blocker "${blockerId}"`);
+        return;
       }
     }
     return () => {
@@ -764,6 +784,12 @@ function useScheduledBlocker(blockerId, config) {
 function capitalizeFirst(str) {
   return str.charAt(0).toUpperCase() + str.slice(1);
 }
+function getAnalyticsWindow() {
+  if (typeof window === "undefined") {
+    return void 0;
+  }
+  return window;
+}
 function buildEventData(context) {
   const eventData = {
     blocker_id: context.blockerId
@@ -781,20 +807,23 @@ function buildEventData(context) {
   return eventData;
 }
 function trackGoogleAnalytics(action, eventData) {
-  if (window.gtag) {
-    window.gtag("event", `ui_blocking_${action}`, eventData);
+  const analyticsWindow = getAnalyticsWindow();
+  if (analyticsWindow?.gtag) {
+    analyticsWindow.gtag("event", `ui_blocking_${action}`, eventData);
   }
 }
 function trackMixpanel(action, eventData) {
-  if (window.mixpanel) {
+  const analyticsWindow = getAnalyticsWindow();
+  if (analyticsWindow?.mixpanel) {
     const eventName = `UI Blocking ${action.split("_").map(capitalizeFirst).join(" ")}`;
-    window.mixpanel.track(eventName, eventData);
+    analyticsWindow.mixpanel.track(eventName, eventData);
   }
 }
 function trackAmplitude(action, eventData) {
-  if (window.amplitude) {
+  const analyticsWindow = getAnalyticsWindow();
+  if (analyticsWindow?.amplitude) {
     const eventName = `UI Blocking ${action.split("_").map(capitalizeFirst).join(" ")}`;
-    window.amplitude.track(eventName, eventData);
+    analyticsWindow.amplitude.track(eventName, eventData);
   }
 }
 function trackCustom(trackFn, action, eventData) {
@@ -831,10 +860,16 @@ function createAnalyticsMiddleware(config) {
 }
 
 // src/middleware/configureMiddleware.ts
+var CONFIGURE_MIDDLEWARE_PREFIX = "middleware-";
 function configureMiddleware(middlewares) {
   const store = uiBlockingStoreApi.getState();
+  store.middlewares.forEach((_, name) => {
+    if (name.startsWith(CONFIGURE_MIDDLEWARE_PREFIX)) {
+      store.unregisterMiddleware(name);
+    }
+  });
   middlewares.forEach((middleware, index) => {
-    const name = `middleware-${index.toString()}`;
+    const name = `${CONFIGURE_MIDDLEWARE_PREFIX}${index.toString()}`;
     store.registerMiddleware(name, middleware);
   });
 }
@@ -918,9 +953,6 @@ function handleRemoveAction(context, blockStartTimes, slowBlockThreshold, onSlow
   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);
   }
 }
@@ -952,10 +984,17 @@ function createTypedHooks() {
   };
 }
 
-Object.defineProperty(exports, "createShallowStore", {
-  enumerable: true,
-  get: function () { return reactZustandToolkit.createShallowStore; }
-});
+// src/index.ts
+function useOptionalContext() {
+  return useOptionalUIBlockingContext();
+}
+function useResolvedStore() {
+  return useResolvedStoreApi();
+}
+function useResolvedStoreWithSelector(selector) {
+  return useResolvedValue(selector);
+}
+
 exports.UIBlockingProvider = UIBlockingProvider;
 exports.configureMiddleware = configureMiddleware;
 exports.createAnalyticsMiddleware = createAnalyticsMiddleware;
@@ -970,6 +1009,12 @@ exports.useConditionalBlocker = useConditionalBlocker;
 exports.useConfirmableBlocker = useConfirmableBlocker;
 exports.useIsBlocked = useIsBlocked;
 exports.useIsInsideUIBlockingProvider = useIsInsideUIBlockingProvider;
+exports.useOptionalContext = useOptionalContext;
+exports.useOptionalUIBlockingContext = useOptionalUIBlockingContext;
+exports.useResolvedStore = useResolvedStore;
+exports.useResolvedStoreApi = useResolvedStoreApi;
+exports.useResolvedStoreWithSelector = useResolvedStoreWithSelector;
+exports.useResolvedValue = useResolvedValue;
 exports.useScheduledBlocker = useScheduledBlocker;
 exports.useUIBlockingContext = useUIBlockingContext;
 exports.useUIBlockingStore = useUIBlockingStore;