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

package/dist/index.d.ts

@@ -1,161 +1,228 @@
+import { ReactNode } from 'react';
 import * as zustand from 'zustand';
 import { StoreApi } from 'zustand';
-export { ShallowStoreBindings, createShallowStore } from '@okyrychenko-dev/react-zustand-toolkit';
-import { ReactNode } from 'react';
+
+type AnalyticsEventData = Record<string, string | number | ReadonlyArray<string> | undefined>;
+type AnalyticsProvider = "ga" | "mixpanel" | "amplitude";
+interface GoogleAnalyticsConfig {
+    provider: "ga";
+}
+interface MixpanelConfig {
+    provider: "mixpanel";
+}
+interface AmplitudeConfig {
+    provider: "amplitude";
+}
+interface CustomAnalyticsConfig {
+    track: (event: string, data: AnalyticsEventData) => void;
+}
+type AnalyticsConfig = GoogleAnalyticsConfig | MixpanelConfig | AmplitudeConfig | CustomAnalyticsConfig;
 
 /**
- * Options for useAsyncAction hook
+ * Configuration options for creating or updating a blocker.
+ *
+ * All fields are optional. Defaults will be applied for any missing values:
+ * - `scope`: "global"
+ * - `reason`: "Blocking UI"
+ * - `priority`: 50
+ * - `timestamp`: Current time
+ *
+ * @example
+ * Basic configuration
+ * ```ts
+ * const config: BlockerConfig = {
+ *   scope: 'form',
+ *   reason: 'Submitting data...',
+ *   priority: 70
+ * };
+ * ```
+ *
+ * @example
+ * With timeout and callback
+ * ```ts
+ * const config: BlockerConfig = {
+ *   scope: ['form', 'navigation'],
+ *   reason: 'Critical operation in progress',
+ *   priority: 90,
+ *   timeout: 30000, // 30 seconds
+ *   onTimeout: (id) => {
+ *     console.warn(`Blocker ${id} timed out`);
+ *   }
+ * };
+ * ```
+ *
+ * @public
+ * @since 0.6.0
  */
-interface UseAsyncActionOptions {
-    /** Timeout in milliseconds after which the blocker will be automatically removed */
+interface BlockerConfig {
+    scope?: string | ReadonlyArray<string>;
+    reason?: string;
+    /** Priority level (negative values are normalized to 0) */
+    priority?: number;
+    timestamp?: number;
+    /** Automatically remove the blocker after N milliseconds */
     timeout?: number;
     /** Callback invoked when the blocker is automatically removed due to timeout */
     onTimeout?: (blockerId: string) => void;
 }
 /**
- * Wraps async functions with automatic UI blocking during execution.
- *
- * Creates a wrapper function that automatically:
- * 1. Adds a blocker before executing the async function
- * 2. Executes the async function
- * 3. Removes the blocker after completion (success or failure)
+ * Internal representation of a blocker with all fields populated.
  *
- * Each invocation generates a unique blocker ID (actionId-counter), allowing
- * multiple concurrent executions of the same action without ID conflicts.
- * The blocker is removed even if the async function throws an error.
+ * This is the stored format in the Map. All optional fields from {@link BlockerConfig}
+ * are converted to required fields with default values applied.
  *
- * Works with both the global store and isolated provider instances (via UIBlockingProvider).
+ * @internal This type is primarily for internal use. Users should work with
+ *           {@link BlockerConfig} for configuration and {@link BlockerInfo} for
+ *           reading blocker data.
  *
- * @template T - The return type of the async function being wrapped
- * @param actionId - Base identifier for the action. Used in blocker ID and default reason.
- *                   Example: "saveForm", "fetchData", "submitOrder"
- * @param scope - Scope(s) to block during execution. Can be a single scope or array.
- *                Defaults to "global" if not specified.
- * @param options - Optional configuration
- * @param options.timeout - Timeout in milliseconds. Blocker auto-removes after this duration.
- * @param options.onTimeout - Callback invoked when blocker times out before async completes
+ * @since 0.6.0
+ */
+interface StoredBlocker {
+    scope: string | ReadonlyArray<string>;
+    reason: string;
+    priority: number;
+    timestamp: number;
+    /** Timeout duration in milliseconds (if set) */
+    timeout?: number;
+    /** Internal timeout ID for cleanup */
+    timeoutId?: ReturnType<typeof setTimeout>;
+    /** Callback invoked when the blocker is automatically removed due to timeout */
+    onTimeout?: (blockerId: string) => void;
+}
+/**
+ * Complete blocker information including its unique identifier.
  *
- * @returns Wrapper function that accepts an async function and returns a Promise with the same type
+ * This type extends {@link StoredBlocker} with the blocker's ID, making it
+ * suitable for reading and displaying blocker information. Returned by
+ * {@link UIBlockingStoreActions.getBlockingInfo} and used by {@link useBlockingInfo}.
  *
  * @example
- * Basic form submission
- * ```tsx
- * function MyForm() {
- *   const executeWithBlocking = useAsyncAction('saveForm', 'form');
- *
- *   const handleSubmit = async (e) => {
- *     e.preventDefault();
+ * Accessing blocker info
+ * ```ts
+ * const blockers: BlockerInfo[] = store.getState().getBlockingInfo('form');
+ * blockers.forEach(blocker => {
+ *   console.log(`${blocker.id}: ${blocker.reason} (priority: ${blocker.priority})`);
+ * });
+ * ```
  *
- *     await executeWithBlocking(async () => {
- *       const response = await fetch('/api/save', {
- *         method: 'POST',
- *         body: JSON.stringify(formData)
- *       });
- *       return response.json();
- *     });
+ * @public
+ * @since 0.6.0
+ */
+interface BlockerInfo extends Omit<StoredBlocker, "timeoutId"> {
+    id: string;
+}
+/**
+ * Internal state structure of the UI blocking store.
  *
- *     alert('Form saved!');
- *   };
+ * Contains the core data structures for managing blockers and middleware.
+ * This state is combined with {@link UIBlockingStoreActions} to create the
+ * complete {@link UIBlockingStore} type.
  *
- *   return <form onSubmit={handleSubmit}>...</form>;
- * }
- * ```
+ * @internal
+ * @since 0.6.0
+ */
+interface UIBlockingStoreState {
+    activeBlockers: Map<string, StoredBlocker>;
+    middlewares: Map<string, Middleware>;
+}
+/**
+ * All available actions for managing UI blocking state.
  *
- * @example
- * With timeout and error handling
- * ```tsx
- * const executeWithBlocking = useAsyncAction(
- *   'fetchData',
- *   ['global', 'data'],
- *   {
- *     timeout: 30000, // 30 seconds
- *     onTimeout: (blockerId) => {
- *       console.warn(`Operation ${blockerId} timed out`);
- *     }
- *   }
- * );
+ * These methods allow adding, removing, updating blockers, checking blocking status,
+ * and managing middleware. Combined with {@link UIBlockingStoreState} to form
+ * the complete {@link UIBlockingStore} type.
  *
- * const loadData = async () => {
- *   try {
- *     const data = await executeWithBlocking(async () => {
- *       return await fetchDataFromAPI();
- *     });
- *     setData(data);
- *   } catch (error) {
- *     console.error('Failed to load data:', error);
- *     // Blocker is automatically removed even on error
- *   }
- * };
- * ```
+ * All actions are safe to call multiple times and handle edge cases gracefully.
  *
  * @example
- * Multiple concurrent actions
- * ```tsx
- * function FileUploader() {
- *   const uploadWithBlocking = useAsyncAction('upload', 'uploads');
+ * Using store actions directly
+ * ```ts
+ * import { uiBlockingStoreApi } from '@okyrychenko-dev/react-action-guard';
  *
- *   const uploadFiles = async (files) => {
- *     // Each upload gets unique blocker ID (upload-1, upload-2, etc.)
- *     const promises = files.map(file =>
- *       uploadWithBlocking(() => uploadFile(file))
- *     );
+ * // Add a blocker
+ * uiBlockingStoreApi.getState().addBlocker('my-blocker', {
+ *   scope: 'form',
+ *   reason: 'Processing...'
+ * });
  *
- *     await Promise.all(promises);
- *   };
+ * // Check if blocked
+ * const isBlocked = uiBlockingStoreApi.getState().isBlocked('form');
  *
- *   return <...>;
- * }
+ * // Remove blocker
+ * uiBlockingStoreApi.getState().removeBlocker('my-blocker');
  * ```
  *
+ * @public
+ * @since 0.6.0
+ */
+interface UIBlockingStoreActions {
+    addBlocker: (id: string, config?: BlockerConfig) => void;
+    updateBlocker: (id: string, config?: Partial<BlockerConfig>) => void;
+    removeBlocker: (id: string) => void;
+    isBlocked: (scope?: string | ReadonlyArray<string>) => boolean;
+    getBlockingInfo: (scope: string) => ReadonlyArray<BlockerInfo>;
+    clearAllBlockers: VoidFunction;
+    clearBlockersForScope: (scope: string) => void;
+    registerMiddleware: (name: string, middleware: Middleware) => void;
+    unregisterMiddleware: (name: string) => void;
+    runMiddlewares: (context: MiddlewareContext) => Promise<void>;
+}
+/**
+ * Complete UI blocking store type combining state and actions.
+ *
+ * This is the full store interface used by hooks like {@link useUIBlockingStore}
+ * and accessible via {@link uiBlockingStoreApi}. It combines all state properties
+ * from {@link UIBlockingStoreState} with all action methods from {@link UIBlockingStoreActions}.
+ *
  * @example
- * Type-safe return value
- * ```tsx
- * interface UserData {
- *   id: string;
- *   name: string;
- * }
+ * Using the complete store
+ * ```ts
+ * import { useUIBlockingStore } from '@okyrychenko-dev/react-action-guard';
  *
- * function UserProfile() {
- *   const executeWithBlocking = useAsyncAction<UserData>('fetchUser', 'user');
+ * function MyComponent() {
+ *   const store = useUIBlockingStore();
  *
- *   const loadUser = async (userId: string) => {
- *     const userData = await executeWithBlocking(async () => {
- *       const response = await fetch(`/api/users/${userId}`);
- *       return response.json(); // TypeScript knows this is UserData
- *     });
+ *   // Access state
+ *   console.log(store.activeBlockers.size);
  *
- *     // userData is typed as UserData
- *     console.log(userData.name);
- *   };
+ *   // Call actions
+ *   store.addBlocker('my-blocker', { scope: 'form' });
  *
- *   return <...>;
+ *   return <div>...</div>;
  * }
  * ```
  *
- * @see {@link useBlocker} for manual blocker management
- * @see {@link useIsBlocked} to check blocking state
- * @see {@link UseAsyncActionOptions} for available options
- *
  * @public
  * @since 0.6.0
  */
-declare function useAsyncAction<T = unknown>(actionId: string, scope?: string | ReadonlyArray<string>, options?: UseAsyncActionOptions): (asyncFn: () => Promise<T>) => Promise<T>;
-
-type AnalyticsEventData = Record<string, string | number | ReadonlyArray<string> | undefined>;
-type AnalyticsProvider = "ga" | "mixpanel" | "amplitude";
-interface GoogleAnalyticsConfig {
-    provider: "ga";
-}
-interface MixpanelConfig {
-    provider: "mixpanel";
-}
-interface AmplitudeConfig {
-    provider: "amplitude";
-}
-interface CustomAnalyticsConfig {
-    track: (event: string, data: AnalyticsEventData) => void;
+type UIBlockingStore = UIBlockingStoreState & UIBlockingStoreActions;
+interface ShallowStoreBindings<StoreState> {
+    useStore: {
+        (): StoreState;
+        <T>(selector: (state: StoreState) => T): T;
+    };
+    useStoreApi: StoreApi<StoreState>;
 }
-type AnalyticsConfig = GoogleAnalyticsConfig | MixpanelConfig | AmplitudeConfig | CustomAnalyticsConfig;
+
+declare const uiBlockingStoreApi: Omit<zustand.StoreApi<UIBlockingStore>, "setState" | "devtools"> & {
+    setState(partial: UIBlockingStore | Partial<UIBlockingStore> | ((state: UIBlockingStore) => UIBlockingStore | Partial<UIBlockingStore>), replace?: false | undefined, action?: (string | {
+        [x: string]: unknown;
+        [x: number]: unknown;
+        [x: symbol]: unknown;
+        type: string;
+    }) | undefined): void;
+    setState(state: UIBlockingStore | ((state: UIBlockingStore) => UIBlockingStore), replace: true, action?: (string | {
+        [x: string]: unknown;
+        [x: number]: unknown;
+        [x: symbol]: unknown;
+        type: string;
+    }) | undefined): void;
+    devtools: {
+        cleanup: () => void;
+    };
+};
+declare function useUIBlockingStore(): UIBlockingStore;
+declare function useUIBlockingStore<T>(selector: (state: UIBlockingStore) => T, equalityFn?: (a: T, b: T) => boolean): T;
 
 type BlockingAction = "add" | "update" | "remove" | "timeout" | "clear" | "clear_scope";
 type MiddlewareBlockerConfig = BlockerConfig;
@@ -369,12 +436,12 @@ interface PerformanceConfig {
 /**
  * Creates middleware for monitoring blocker performance and detecting slow blocks.
  *
- * Tracks the duration of each blocker (from add to remove) and warns when a blocker
- * exceeds the configured threshold. Useful for identifying performance issues,
- * stuck blockers, or operations that take too long.
+ * Tracks the duration of each blocker (from add to remove) and invokes an optional
+ * callback when a blocker exceeds the configured threshold. Useful for identifying
+ * performance issues, stuck blockers, or operations that take too long.
  *
- * Automatically logs warnings to console for slow blocks and optionally invokes
- * a callback for custom handling (e.g., error reporting, analytics).
+ * The middleware is side-effect free by default; use `onSlowBlock` for custom
+ * reporting, logging, or analytics integration.
  *
  * @param config - Performance monitoring configuration
  * @param config.slowBlockThreshold - Duration in ms before considering a block "slow".
@@ -392,7 +459,7 @@ interface PerformanceConfig {
  * const performanceMiddleware = createPerformanceMiddleware();
  *
  * configureMiddleware([performanceMiddleware]);
- * // Warns if any blocker lasts > 3 seconds
+ * // Track slow blocks via onSlowBlock if any blocker lasts > 3 seconds
  * ```
  *
  * @example
@@ -454,202 +521,290 @@ interface PerformanceConfig {
 declare function createPerformanceMiddleware(config?: PerformanceConfig): Middleware;
 
 /**
- * Configuration options for creating or updating a blocker.
+ * Props for the {@link UIBlockingProvider} component.
  *
- * All fields are optional. Defaults will be applied for any missing values:
- * - `scope`: "global"
- * - `reason`: "Blocking UI"
- * - `priority`: 50
- * - `timestamp`: Current time
+ * Configures an isolated UI blocking store instance for a subtree of your app.
+ * Useful for SSR, testing, micro-frontends, or any scenario where you need
+ * independent blocking state.
+ *
+ * @public
+ * @since 0.6.0
+ */
+interface UIBlockingProviderProps {
+    children: ReactNode;
+    /** Enable Redux DevTools integration (default: true in development) */
+    enableDevtools?: boolean;
+    /** Name for Redux DevTools (default: "UIBlocking") */
+    devtoolsName?: string;
+    /** Initial middlewares to register */
+    middlewares?: ReadonlyArray<Middleware>;
+}
+/**
+ * Base provider implementation created using toolkit's createStoreProvider.
+ * @internal
+ */
+declare const useUIBlockingContext: () => StoreApi<UIBlockingStore>;
+declare const useIsInsideUIBlockingProvider: () => boolean;
+declare const useOptionalUIBlockingContext: () => StoreApi<UIBlockingStore> | null;
+declare function useUIBlockingStoreFromContext(): UIBlockingStore;
+declare function useUIBlockingStoreFromContext<T>(selector: (state: UIBlockingStore) => T, equalityFn?: (a: T, b: T) => boolean): T;
+/**
+ * Provider component for isolated UI blocking state management.
+ *
+ * Creates an independent store instance for a subtree of your application.
+ * Each provider has its own isolated blocking state, separate from the global
+ * store and other provider instances.
+ *
+ * **Use cases:**
+ * - Server-Side Rendering (SSR) - Avoid state sharing between requests
+ * - Testing - Isolated state for each test
+ * - Micro-frontends - Independent blocking state per micro-app
+ * - Modals/Dialogs - Scoped blocking within a dialog
+ *
+ * Uses `createStoreProvider` from `@okyrychenko-dev/react-zustand-toolkit` with
+ * built-in DevTools support and middleware registration.
+ *
+ * @param props - Provider configuration
+ * @param props.children - React children to wrap with the provider
+ * @param props.enableDevtools - Enable Redux DevTools integration. Defaults to true in development, false in production.
+ * @param props.devtoolsName - Name displayed in Redux DevTools. Defaults to "UIBlocking".
+ * @param props.middlewares - Array of middleware functions to register on store creation
  *
  * @example
- * Basic configuration
- * ```ts
- * const config: BlockerConfig = {
- *   scope: 'form',
- *   reason: 'Submitting data...',
- *   priority: 70
- * };
+ * Basic SSR setup
+ * ```tsx
+ * import { UIBlockingProvider } from '@okyrychenko-dev/react-action-guard';
+ *
+ * function App() {
+ *   return (
+ *     <UIBlockingProvider>
+ *       <MyApplication />
+ *     </UIBlockingProvider>
+ *   );
+ * }
  * ```
  *
  * @example
- * With timeout and callback
- * ```ts
- * const config: BlockerConfig = {
- *   scope: ['form', 'navigation'],
- *   reason: 'Critical operation in progress',
- *   priority: 90,
- *   timeout: 30000, // 30 seconds
- *   onTimeout: (id) => {
- *     console.warn(`Blocker ${id} timed out`);
- *   }
- * };
+ * With middleware and custom DevTools name
+ * ```tsx
+ * import { UIBlockingProvider, loggerMiddleware } from '@okyrychenko-dev/react-action-guard';
+ *
+ * function App() {
+ *   return (
+ *     <UIBlockingProvider
+ *       enableDevtools={true}
+ *       devtoolsName="MyApp-UIBlocking"
+ *       middlewares={[loggerMiddleware]}
+ *     >
+ *       <MyApplication />
+ *     </UIBlockingProvider>
+ *   );
+ * }
  * ```
  *
+ * @example
+ * Multiple providers for micro-frontends
+ * ```tsx
+ * function MicroFrontendApp() {
+ *   return (
+ *     <div>
+ *       <UIBlockingProvider devtoolsName="MicroApp1">
+ *         <MicroApp1 />
+ *       </UIBlockingProvider>
+ *
+ *       <UIBlockingProvider devtoolsName="MicroApp2">
+ *         <MicroApp2 />
+ *       </UIBlockingProvider>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Testing with isolated state
+ * ```tsx
+ * // In your test file
+ * import { render } from '@testing-library/react';
+ * import { UIBlockingProvider } from '@okyrychenko-dev/react-action-guard';
+ *
+ * test('blocker behavior', () => {
+ *   render(
+ *     <UIBlockingProvider enableDevtools={false}>
+ *       <ComponentUnderTest />
+ *     </UIBlockingProvider>
+ *   );
+ *   // Each test gets isolated state
+ * });
+ * ```
+ *
+ * @see {@link useUIBlockingContext} to access the store from context
+ * @see {@link useIsInsideUIBlockingProvider} to check if inside a provider
+ * @see {@link UIBlockingProviderProps} for prop details
+ *
  * @public
  * @since 0.6.0
  */
-interface BlockerConfig {
-    scope?: string | ReadonlyArray<string>;
-    reason?: string;
-    /** Priority level (negative values are normalized to 0) */
-    priority?: number;
-    timestamp?: number;
-    /** Automatically remove the blocker after N milliseconds */
-    timeout?: number;
-    /** Callback invoked when the blocker is automatically removed due to timeout */
-    onTimeout?: (blockerId: string) => void;
-}
+declare function UIBlockingProvider({ children, enableDevtools, devtoolsName, middlewares, }: UIBlockingProviderProps): ReactNode;
+
 /**
- * Internal representation of a blocker with all fields populated.
+ * Hook that resolves to either the context store or global store
  *
- * This is the stored format in the Map. All optional fields from {@link BlockerConfig}
- * are converted to required fields with default values applied.
+ * This hook automatically uses the store from UIBlockingProvider if available,
+ * otherwise falls back to the global store. This enables both patterns:
  *
- * @internal This type is primarily for internal use. Users should work with
- *           {@link BlockerConfig} for configuration and {@link BlockerInfo} for
- *           reading blocker data.
+ * 1. Global store (default behavior, no Provider needed)
+ * 2. Context store (for SSR, testing, micro-frontends)
  *
- * @since 0.6.0
+ * @returns The resolved store API
  */
-interface StoredBlocker {
-    scope: string | ReadonlyArray<string>;
-    reason: string;
-    priority: number;
-    timestamp: number;
-    /** Timeout duration in milliseconds (if set) */
+declare function useResolvedStoreApi(): StoreApi<UIBlockingStore>;
+/**
+ * Hook to use the resolved store with a selector
+ *
+ * Automatically applies shallow comparison to prevent unnecessary re-renders.
+ *
+ * @param selector - Selector function to pick state from the store
+ * @returns Selected state value
+ */
+declare function useResolvedValue<T>(selector: (state: UIBlockingStore) => T): T;
+
+/**
+ * Options for useAsyncAction hook
+ */
+interface UseAsyncActionOptions {
+    /** Timeout in milliseconds after which the blocker will be automatically removed */
     timeout?: number;
-    /** Internal timeout ID for cleanup */
-    timeoutId?: ReturnType<typeof setTimeout>;
     /** Callback invoked when the blocker is automatically removed due to timeout */
     onTimeout?: (blockerId: string) => void;
 }
 /**
- * Complete blocker information including its unique identifier.
+ * Wraps async functions with automatic UI blocking during execution.
  *
- * This type extends {@link StoredBlocker} with the blocker's ID, making it
- * suitable for reading and displaying blocker information. Returned by
- * {@link UIBlockingStoreActions.getBlockingInfo} and used by {@link useBlockingInfo}.
+ * Creates a wrapper function that automatically:
+ * 1. Adds a blocker before executing the async function
+ * 2. Executes the async function
+ * 3. Removes the blocker after completion (success or failure)
  *
- * @example
- * Accessing blocker info
- * ```ts
- * const blockers: BlockerInfo[] = store.getState().getBlockingInfo('form');
- * blockers.forEach(blocker => {
- *   console.log(`${blocker.id}: ${blocker.reason} (priority: ${blocker.priority})`);
- * });
- * ```
+ * Each invocation generates a unique blocker ID (actionId-counter), allowing
+ * multiple concurrent executions of the same action without ID conflicts.
+ * The blocker is removed even if the async function throws an error.
  *
- * @public
- * @since 0.6.0
- */
-interface BlockerInfo extends StoredBlocker {
-    id: string;
-}
-/**
- * Internal state structure of the UI blocking store.
+ * Works with both the global store and isolated provider instances (via UIBlockingProvider).
  *
- * Contains the core data structures for managing blockers and middleware.
- * This state is combined with {@link UIBlockingStoreActions} to create the
- * complete {@link UIBlockingStore} type.
+ * @template T - The return type of the async function being wrapped
+ * @param actionId - Base identifier for the action. Used in blocker ID and default reason.
+ *                   Example: "saveForm", "fetchData", "submitOrder"
+ * @param scope - Scope(s) to block during execution. Can be a single scope or array.
+ *                Defaults to "global" if not specified.
+ * @param options - Optional configuration
+ * @param options.timeout - Timeout in milliseconds. Blocker auto-removes after this duration.
+ * @param options.onTimeout - Callback invoked when blocker times out before async completes
+ *
+ * @returns Wrapper function that accepts an async function and returns a Promise with the same type
+ *
+ * @example
+ * Basic form submission
+ * ```tsx
+ * function MyForm() {
+ *   const executeWithBlocking = useAsyncAction('saveForm', 'form');
+ *
+ *   const handleSubmit = async (e) => {
+ *     e.preventDefault();
  *
- * @internal
- * @since 0.6.0
- */
-interface UIBlockingStoreState {
-    activeBlockers: Map<string, StoredBlocker>;
-    middlewares: Map<string, Middleware>;
-}
-/**
- * All available actions for managing UI blocking state.
+ *     await executeWithBlocking(async () => {
+ *       const response = await fetch('/api/save', {
+ *         method: 'POST',
+ *         body: JSON.stringify(formData)
+ *       });
+ *       return response.json();
+ *     });
  *
- * These methods allow adding, removing, updating blockers, checking blocking status,
- * and managing middleware. Combined with {@link UIBlockingStoreState} to form
- * the complete {@link UIBlockingStore} type.
+ *     alert('Form saved!');
+ *   };
  *
- * All actions are safe to call multiple times and handle edge cases gracefully.
+ *   return <form onSubmit={handleSubmit}>...</form>;
+ * }
+ * ```
  *
  * @example
- * Using store actions directly
- * ```ts
- * import { uiBlockingStoreApi } from '@okyrychenko-dev/react-action-guard';
+ * With timeout and error handling
+ * ```tsx
+ * const executeWithBlocking = useAsyncAction(
+ *   'fetchData',
+ *   ['global', 'data'],
+ *   {
+ *     timeout: 30000, // 30 seconds
+ *     onTimeout: (blockerId) => {
+ *       console.warn(`Operation ${blockerId} timed out`);
+ *     }
+ *   }
+ * );
  *
- * // Add a blocker
- * uiBlockingStoreApi.getState().addBlocker('my-blocker', {
- *   scope: 'form',
- *   reason: 'Processing...'
- * });
+ * const loadData = async () => {
+ *   try {
+ *     const data = await executeWithBlocking(async () => {
+ *       return await fetchDataFromAPI();
+ *     });
+ *     setData(data);
+ *   } catch (error) {
+ *     console.error('Failed to load data:', error);
+ *     // Blocker is automatically removed even on error
+ *   }
+ * };
+ * ```
  *
- * // Check if blocked
- * const isBlocked = uiBlockingStoreApi.getState().isBlocked('form');
+ * @example
+ * Multiple concurrent actions
+ * ```tsx
+ * function FileUploader() {
+ *   const uploadWithBlocking = useAsyncAction('upload', 'uploads');
  *
- * // Remove blocker
- * uiBlockingStoreApi.getState().removeBlocker('my-blocker');
- * ```
+ *   const uploadFiles = async (files) => {
+ *     // Each upload gets unique blocker ID (upload-1, upload-2, etc.)
+ *     const promises = files.map(file =>
+ *       uploadWithBlocking(() => uploadFile(file))
+ *     );
  *
- * @public
- * @since 0.6.0
- */
-interface UIBlockingStoreActions {
-    addBlocker: (id: string, config?: BlockerConfig) => void;
-    updateBlocker: (id: string, config?: Partial<BlockerConfig>) => void;
-    removeBlocker: (id: string) => void;
-    isBlocked: (scope?: string | ReadonlyArray<string>) => boolean;
-    getBlockingInfo: (scope: string) => ReadonlyArray<BlockerInfo>;
-    clearAllBlockers: VoidFunction;
-    clearBlockersForScope: (scope: string) => void;
-    registerMiddleware: (name: string, middleware: Middleware) => void;
-    unregisterMiddleware: (name: string) => void;
-    runMiddlewares: (context: MiddlewareContext) => Promise<void>;
-}
-/**
- * Complete UI blocking store type combining state and actions.
+ *     await Promise.all(promises);
+ *   };
  *
- * This is the full store interface used by hooks like {@link useUIBlockingStore}
- * and accessible via {@link uiBlockingStoreApi}. It combines all state properties
- * from {@link UIBlockingStoreState} with all action methods from {@link UIBlockingStoreActions}.
+ *   return <...>;
+ * }
+ * ```
  *
  * @example
- * Using the complete store
- * ```ts
- * import { useUIBlockingStore } from '@okyrychenko-dev/react-action-guard';
+ * Type-safe return value
+ * ```tsx
+ * interface UserData {
+ *   id: string;
+ *   name: string;
+ * }
  *
- * function MyComponent() {
- *   const store = useUIBlockingStore();
+ * function UserProfile() {
+ *   const executeWithBlocking = useAsyncAction<UserData>('fetchUser', 'user');
  *
- *   // Access state
- *   console.log(store.activeBlockers.size);
+ *   const loadUser = async (userId: string) => {
+ *     const userData = await executeWithBlocking(async () => {
+ *       const response = await fetch(`/api/users/${userId}`);
+ *       return response.json(); // TypeScript knows this is UserData
+ *     });
  *
- *   // Call actions
- *   store.addBlocker('my-blocker', { scope: 'form' });
+ *     // userData is typed as UserData
+ *     console.log(userData.name);
+ *   };
  *
- *   return <div>...</div>;
+ *   return <...>;
  * }
  * ```
  *
+ * @see {@link useBlocker} for manual blocker management
+ * @see {@link useIsBlocked} to check blocking state
+ * @see {@link UseAsyncActionOptions} for available options
+ *
  * @public
  * @since 0.6.0
  */
-type UIBlockingStore = UIBlockingStoreState & UIBlockingStoreActions;
-
-/**
- * UI Blocking Store
- *
- * Global Zustand store for managing UI blocking state across the application.
- *
- * Features:
- * - Priority-based blocking system
- * - Scope-based blocking (global, specific areas, or multiple scopes)
- * - Automatic cleanup on unmount (when using hooks)
- * - DevTools integration for debugging
- * - Automatic shallow comparison for selectors
- *
- */
-declare const useUIBlockingStore: {
-    (): UIBlockingStore;
-    <T>(selector: (state: UIBlockingStore) => T): T;
-};
-declare const uiBlockingStoreApi: zustand.StoreApi<UIBlockingStore>;
+declare function useAsyncAction<T = unknown>(actionId: string, scope?: string | ReadonlyArray<string>, options?: UseAsyncActionOptions): (asyncFn: () => Promise<T>) => Promise<T>;
 
 /**
  * Automatically manages a UI blocker based on component lifecycle.
@@ -948,16 +1103,10 @@ interface ConditionalBlockerConfig<TState = unknown> extends Omit<BlockerConfig,
  * Without state parameter (simple condition)
  * ```tsx
  * useConditionalBlocker('low-battery', {
- *   condition: () => {
- *     // Check battery level if available
- *     if ('getBattery' in navigator) {
- *       return navigator.getBattery().then(b => b.level < 0.05);
- *     }
- *     return false;
- *   },
+ *   condition: () => !navigator.onLine,
  *   checkInterval: 30000, // Check every 30 seconds
  *   scope: 'heavy-operations',
- *   reason: 'Battery level too low for this operation',
+ *   reason: 'Internet connection is required for this operation',
  *   priority: 80
  * });
  * ```
@@ -1442,130 +1591,16 @@ interface TypedHooks<TScope extends string> {
 declare function createTypedHooks<TScope extends string>(): TypedHooks<TScope>;
 
 /**
- * Props for the {@link UIBlockingProvider} component.
- *
- * Configures an isolated UI blocking store instance for a subtree of your app.
- * Useful for SSR, testing, micro-frontends, or any scenario where you need
- * independent blocking state.
- *
- * @public
- * @since 0.6.0
+ * @deprecated Use `useOptionalUIBlockingContext`.
  */
-interface UIBlockingProviderProps {
-    children: ReactNode;
-    /** Enable Redux DevTools integration (default: true in development) */
-    enableDevtools?: boolean;
-    /** Name for Redux DevTools (default: "UIBlocking") */
-    devtoolsName?: string;
-    /** Initial middlewares to register */
-    middlewares?: ReadonlyArray<Middleware>;
-}
+declare function useOptionalContext(): ReturnType<typeof useOptionalUIBlockingContext>;
 /**
- * Base provider implementation created using toolkit's createStoreProvider.
- * @internal
+ * @deprecated Use `useResolvedStoreApi`.
  */
-declare const useUIBlockingContext: () => StoreApi<UIBlockingStore>;
-declare const useUIBlockingStoreFromContext: {
-    (): UIBlockingStore;
-    <T>(selector: (state: UIBlockingStore) => T): T;
-};
-declare const useIsInsideUIBlockingProvider: () => boolean;
+declare function useResolvedStore(): StoreApi<UIBlockingStore>;
 /**
- * Provider component for isolated UI blocking state management.
- *
- * Creates an independent store instance for a subtree of your application.
- * Each provider has its own isolated blocking state, separate from the global
- * store and other provider instances.
- *
- * **Use cases:**
- * - Server-Side Rendering (SSR) - Avoid state sharing between requests
- * - Testing - Isolated state for each test
- * - Micro-frontends - Independent blocking state per micro-app
- * - Modals/Dialogs - Scoped blocking within a dialog
- *
- * Uses `createStoreProvider` from `@okyrychenko-dev/react-zustand-toolkit` with
- * built-in DevTools support and middleware registration.
- *
- * @param props - Provider configuration
- * @param props.children - React children to wrap with the provider
- * @param props.enableDevtools - Enable Redux DevTools integration. Defaults to true in development, false in production.
- * @param props.devtoolsName - Name displayed in Redux DevTools. Defaults to "UIBlocking".
- * @param props.middlewares - Array of middleware functions to register on store creation
- *
- * @example
- * Basic SSR setup
- * ```tsx
- * import { UIBlockingProvider } from '@okyrychenko-dev/react-action-guard';
- *
- * function App() {
- *   return (
- *     <UIBlockingProvider>
- *       <MyApplication />
- *     </UIBlockingProvider>
- *   );
- * }
- * ```
- *
- * @example
- * With middleware and custom DevTools name
- * ```tsx
- * import { UIBlockingProvider, loggerMiddleware } from '@okyrychenko-dev/react-action-guard';
- *
- * function App() {
- *   return (
- *     <UIBlockingProvider
- *       enableDevtools={true}
- *       devtoolsName="MyApp-UIBlocking"
- *       middlewares={[loggerMiddleware]}
- *     >
- *       <MyApplication />
- *     </UIBlockingProvider>
- *   );
- * }
- * ```
- *
- * @example
- * Multiple providers for micro-frontends
- * ```tsx
- * function MicroFrontendApp() {
- *   return (
- *     <div>
- *       <UIBlockingProvider devtoolsName="MicroApp1">
- *         <MicroApp1 />
- *       </UIBlockingProvider>
- *
- *       <UIBlockingProvider devtoolsName="MicroApp2">
- *         <MicroApp2 />
- *       </UIBlockingProvider>
- *     </div>
- *   );
- * }
- * ```
- *
- * @example
- * Testing with isolated state
- * ```tsx
- * // In your test file
- * import { render } from '@testing-library/react';
- * import { UIBlockingProvider } from '@okyrychenko-dev/react-action-guard';
- *
- * test('blocker behavior', () => {
- *   render(
- *     <UIBlockingProvider enableDevtools={false}>
- *       <ComponentUnderTest />
- *     </UIBlockingProvider>
- *   );
- *   // Each test gets isolated state
- * });
- * ```
- *
- * @see {@link useUIBlockingContext} to access the store from context
- * @see {@link useIsInsideUIBlockingProvider} to check if inside a provider
- * @see {@link UIBlockingProviderProps} for prop details
- *
- * @public
- * @since 0.6.0
+ * @deprecated Use `useResolvedValue`.
  */
-declare function UIBlockingProvider({ children, enableDevtools, devtoolsName, middlewares, }: UIBlockingProviderProps): ReactNode;
+declare function useResolvedStoreWithSelector<T>(selector: (state: UIBlockingStore) => T): T;
 
-export { type AmplitudeConfig, type AnalyticsConfig, type AnalyticsEventData, type AnalyticsProvider, type BlockerConfig, type BlockerConfigTyped, type BlockerInfo, type BlockingAction, type BlockingSchedule, type ConditionalBlockerConfig, type ConfirmDialogConfig, type ConfirmableBlockerConfig, type CustomAnalyticsConfig, type DefaultScopes, type GoogleAnalyticsConfig, type Middleware, type MiddlewareContext, type MixpanelConfig, type PerformanceConfig, type ScheduledBlockerConfig, type ScopeValue, type StoredBlocker, type TypedHooks, UIBlockingProvider, type UIBlockingProviderProps, type UIBlockingStore, type UIBlockingStoreActions, type UIBlockingStoreState, type UseAsyncActionOptions, type UseConfirmableBlockerReturn, configureMiddleware, createAnalyticsMiddleware, createPerformanceMiddleware, createTypedHooks, loggerMiddleware, uiBlockingStoreApi, useAsyncAction, useBlocker, useBlockingInfo, useConditionalBlocker, useConfirmableBlocker, useIsBlocked, useIsInsideUIBlockingProvider, useScheduledBlocker, useUIBlockingContext, useUIBlockingStore, useUIBlockingStoreFromContext };
+export { type AmplitudeConfig, type AnalyticsConfig, type AnalyticsEventData, type AnalyticsProvider, type BlockerConfig, type BlockerConfigTyped, type BlockerInfo, type BlockingAction, type BlockingSchedule, type ConditionalBlockerConfig, type ConfirmDialogConfig, type ConfirmableBlockerConfig, type CustomAnalyticsConfig, type DefaultScopes, type GoogleAnalyticsConfig, type Middleware, type MiddlewareContext, type MixpanelConfig, type PerformanceConfig, type ScheduledBlockerConfig, type ScopeValue, type ShallowStoreBindings, type StoredBlocker, type TypedHooks, UIBlockingProvider, type UIBlockingProviderProps, type UIBlockingStore, type UIBlockingStoreActions, type UIBlockingStoreState, type UseAsyncActionOptions, type UseConfirmableBlockerReturn, configureMiddleware, createAnalyticsMiddleware, createPerformanceMiddleware, createTypedHooks, loggerMiddleware, uiBlockingStoreApi, useAsyncAction, useBlocker, useBlockingInfo, useConditionalBlocker, useConfirmableBlocker, useIsBlocked, useIsInsideUIBlockingProvider, useOptionalContext, useOptionalUIBlockingContext, useResolvedStore, useResolvedStoreApi, useResolvedStoreWithSelector, useResolvedValue, useScheduledBlocker, useUIBlockingContext, useUIBlockingStore, useUIBlockingStoreFromContext };