@okyrychenko-dev/react-action-guard 0.3.3 → 0.5.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
 
@@ -51,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:
 
@@ -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)`
@@ -147,7 +178,7 @@ function CheckoutButton() {
 }
 ```
 
-#### `useAsyncAction(actionId, scope)`
+#### `useAsyncAction(actionId, scope, options)`
 
 Wraps an async function with automatic blocking/unblocking.
 
@@ -155,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
 
@@ -172,51 +206,85 @@ 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)`
+#### `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() {
-  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..." />}
+    </>
   );
 }
 ```
@@ -306,21 +374,72 @@ 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`
 
-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:**
 
@@ -328,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", {
@@ -339,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,
     });
   };
@@ -358,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.
@@ -369,7 +514,10 @@ 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, createAnalyticsMiddleware } from "@okyrychenko-dev/react-action-guard";
+import {
+  configureMiddleware,
+  createAnalyticsMiddleware,
+} from "@okyrychenko-dev/react-action-guard";
 
 // Google Analytics
 configureMiddleware([createAnalyticsMiddleware({ provider: "ga" })]);
@@ -405,7 +553,10 @@ configureMiddleware([loggerMiddleware]);
 Monitor blocker performance and detect slow operations.
 
 ```jsx
-import { configureMiddleware, createPerformanceMiddleware } from "@okyrychenko-dev/react-action-guard";
+import {
+  configureMiddleware,
+  createPerformanceMiddleware,
+} from "@okyrychenko-dev/react-action-guard";
 
 configureMiddleware([
   createPerformanceMiddleware({
@@ -417,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:
@@ -475,7 +630,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, createAnalyticsMiddleware } 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.
@@ -489,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
@@ -560,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>
@@ -585,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>
   );
 }
@@ -740,4 +933,4 @@ See [CHANGELOG.md](./CHANGELOG.md) for a detailed list of changes in each versio
 
 ## License
 
-MIT © Olexii Kyrychenko
+MIT © Oleksii Kyrychenko