@okyrychenko-dev/react-action-guard 0.4.0 → 0.5.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:
 
@@ -225,49 +225,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 +428,18 @@ 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)
 - `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
+- `registerMiddleware(name, middleware)` - Register middleware manually
+- `unregisterMiddleware(name)` - Unregister middleware manually
 
 **Example:**
 
@@ -429,7 +447,10 @@ 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, removeBlocker } = useUIBlockingStore((state) => ({
+    addBlocker: state.addBlocker,
+    removeBlocker: state.removeBlocker,
+  }));
 
   const startBlocking = () => {
     addBlocker("custom-blocker", {
@@ -440,7 +461,10 @@ function AdvancedComponent() {
   };
 
   const updatePriority = () => {
-    updateBlocker("custom-blocker", {
+    // Re-add with the same ID to update the config
+    addBlocker("custom-blocker", {
+      scope: ["form", "navigation"],
+      reason: "Critical operation in progress",
       priority: 200,
     });
   };
@@ -459,6 +483,26 @@ 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.
@@ -524,6 +568,10 @@ 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:
@@ -599,23 +647,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 +743,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 +768,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>
   );
 }

package/dist/index.cjs

@@ -1,10 +1,12 @@
 'use strict';
 
 var react = require('react');
+var reactZustandToolkit = require('@okyrychenko-dev/react-zustand-toolkit');
 var zustand = require('zustand');
-var middleware = require('zustand/middleware');
-var shallow = require('zustand/shallow');
+require('zustand/react/shallow');
 var jsxRuntime = require('react/jsx-runtime');
+var shallow = require('zustand/shallow');
+var middleware = require('zustand/middleware');
 
 // src/hooks/useAsyncAction/useAsyncAction.ts
 
@@ -14,13 +16,6 @@ var DEFAULT_REASON = "Unknown";
 var DEFAULT_PRIORITY = 0;
 var ASYNC_ACTION_PRIORITY = 20;
 var DEVTOOLS_NAME = "UIBlocking";
-function createShallowStore(storeCreator) {
-  const storeApi = zustand.createStore(storeCreator);
-  const useScopedStore = (selector) => {
-    return zustand.useStore(storeApi, shallow.useShallow(selector));
-  };
-  return { useStore: useScopedStore, useStoreApi: storeApi };
-}
 function normalizeScopeToArray(scope) {
   if (typeof scope === "string") {
     return [scope];
@@ -221,44 +216,33 @@ var createUIBlockingActions = (set, get) => ({
     });
   }
 });
-var UIBlockingContext = react.createContext(null);
+var {
+  Provider: BaseUIBlockingProvider,
+  useContext: useUIBlockingContext,
+  useContextStore: useUIBlockingStoreFromContext,
+  useIsInsideProvider: useIsInsideUIBlockingProvider,
+  useOptionalContext
+} = reactZustandToolkit.createStoreProvider(createUIBlockingActions, "UIBlocking");
 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);
+  const handleStoreCreate = (store) => {
+    middlewares.forEach((mw, index) => {
+      store.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));
+  };
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    BaseUIBlockingProvider,
+    {
+      enableDevtools,
+      devtoolsName,
+      onStoreCreate: handleStoreCreate,
+      children
+    }
+  );
 }
 
 // src/store/uiBlockingStore.config.ts
@@ -268,11 +252,14 @@ var devtoolsConfig = {
 };
 
 // src/store/uiBlockingStore.store.ts
-var { useStore: useUIBlockingStore, useStoreApi: uiBlockingStoreApi } = createShallowStore(middleware.devtools(createUIBlockingActions, devtoolsConfig));
+var { useStore: useUIBlockingStore, useStoreApi: uiBlockingStoreApi } = reactZustandToolkit.createShallowStore(middleware.devtools(createUIBlockingActions, devtoolsConfig));
 
 // src/context/useResolvedStore.ts
+function useOptionalContextStore() {
+  return useOptionalContext();
+}
 function useResolvedStore() {
-  const contextStore = react.useContext(UIBlockingContext);
+  const contextStore = useOptionalContextStore();
   return contextStore ?? uiBlockingStoreApi;
 }
 function useResolvedStoreWithSelector(selector) {
@@ -719,6 +706,10 @@ function createTypedHooks() {
   };
 }
 
+Object.defineProperty(exports, "createShallowStore", {
+  enumerable: true,
+  get: function () { return reactZustandToolkit.createShallowStore; }
+});
 exports.UIBlockingProvider = UIBlockingProvider;
 exports.configureMiddleware = configureMiddleware;
 exports.createAnalyticsMiddleware = createAnalyticsMiddleware;