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

package/dist/index.d.ts

@@ -13,21 +13,133 @@ interface UseAsyncActionOptions {
     onTimeout?: (blockerId: string) => void;
 }
 /**
- * Hook to wrap async functions with automatic blocking/unblocking
+ * Wraps async functions with automatic UI blocking during execution.
  *
- * Creates a wrapper function that automatically adds a blocker before executing
- * the async function and removes it after completion (success or failure).
+ * 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)
  *
- * Supports both global store and context store (via UIBlockingProvider).
+ * 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.
  *
- * @template T - The return type of the async function
- * @param actionId - Unique identifier for the action (used in blocker ID and reason)
- * @param scope - Scope(s) to block during execution (default: "global")
- * @param options - Optional configuration including timeout
- * @returns Function that wraps async functions with blocking behavior
+ * Works with both the global store and isolated provider instances (via UIBlockingProvider).
  *
+ * @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();
+ *
+ *     await executeWithBlocking(async () => {
+ *       const response = await fetch('/api/save', {
+ *         method: 'POST',
+ *         body: JSON.stringify(formData)
+ *       });
+ *       return response.json();
+ *     });
+ *
+ *     alert('Form saved!');
+ *   };
+ *
+ *   return <form onSubmit={handleSubmit}>...</form>;
+ * }
+ * ```
+ *
+ * @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`);
+ *     }
+ *   }
+ * );
+ *
+ * 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
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * Multiple concurrent actions
+ * ```tsx
+ * function FileUploader() {
+ *   const uploadWithBlocking = useAsyncAction('upload', 'uploads');
+ *
+ *   const uploadFiles = async (files) => {
+ *     // Each upload gets unique blocker ID (upload-1, upload-2, etc.)
+ *     const promises = files.map(file =>
+ *       uploadWithBlocking(() => uploadFile(file))
+ *     );
+ *
+ *     await Promise.all(promises);
+ *   };
+ *
+ *   return <...>;
+ * }
+ * ```
+ *
+ * @example
+ * Type-safe return value
+ * ```tsx
+ * interface UserData {
+ *   id: string;
+ *   name: string;
+ * }
+ *
+ * function UserProfile() {
+ *   const executeWithBlocking = useAsyncAction<UserData>('fetchUser', 'user');
+ *
+ *   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
+ *     });
+ *
+ *     // userData is typed as UserData
+ *     console.log(userData.name);
+ *   };
+ *
+ *   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
  */
-declare const useAsyncAction: <T = unknown>(actionId: string, scope?: string | ReadonlyArray<string>, options?: UseAsyncActionOptions) => ((asyncFn: () => Promise<T>) => Promise<T>);
+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";
@@ -58,30 +170,324 @@ interface MiddlewareContext {
 }
 type Middleware = (context: MiddlewareContext) => void | Promise<void>;
 
-declare const createAnalyticsMiddleware: (config: AnalyticsConfig) => Middleware;
+/**
+ * Creates middleware for tracking blocker events to analytics platforms.
+ *
+ * Automatically tracks all blocker actions (add, remove, update, timeout, clear)
+ * to your analytics platform. Supports Google Analytics, Mixpanel, Amplitude,
+ * and custom analytics providers.
+ *
+ * Event data includes: blockerId, action, scope, reason, priority, timestamp,
+ * and duration (for remove events).
+ *
+ * @param config - Analytics configuration specifying provider and credentials
+ *
+ * @example
+ * Google Analytics integration
+ * ```ts
+ * import { configureMiddleware, createAnalyticsMiddleware } from '@okyrychenko-dev/react-action-guard';
+ *
+ * const analyticsMiddleware = createAnalyticsMiddleware({
+ *   provider: 'ga',
+ *   trackingId: 'GA-XXXXX-Y'
+ * });
+ *
+ * configureMiddleware([analyticsMiddleware]);
+ * ```
+ *
+ * @example
+ * Mixpanel integration
+ * ```ts
+ * const analyticsMiddleware = createAnalyticsMiddleware({
+ *   provider: 'mixpanel',
+ *   token: 'your_mixpanel_token',
+ *   options: {
+ *     debug: true
+ *   }
+ * });
+ *
+ * configureMiddleware([analyticsMiddleware]);
+ * ```
+ *
+ * @example
+ * Custom analytics provider
+ * ```ts
+ * const analyticsMiddleware = createAnalyticsMiddleware({
+ *   track: (eventName, eventData) => {
+ *     // Send to your custom analytics
+ *     myAnalytics.track(eventName, {
+ *       ...eventData,
+ *       userId: getCurrentUserId()
+ *     });
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * Amplitude with user properties
+ * ```ts
+ * const analyticsMiddleware = createAnalyticsMiddleware({
+ *   provider: 'amplitude',
+ *   apiKey: 'your_amplitude_key',
+ *   userId: 'user-123',
+ *   userProperties: {
+ *     plan: 'premium',
+ *     role: 'admin'
+ *   }
+ * });
+ * ```
+ *
+ * @see {@link AnalyticsConfig} for configuration options
+ * @see {@link configureMiddleware} for registering middleware
+ *
+ * @public
+ * @since 0.6.0
+ */
+declare function createAnalyticsMiddleware(config: AnalyticsConfig): Middleware;
 
 /**
- * Configure middleware for the UI blocking store
+ * Configures and registers multiple middleware functions for the UI blocking store.
+ *
+ * Convenience function that registers an array of middleware at once. Each middleware
+ * is automatically assigned a unique name based on its array index ("middleware-0",
+ * "middleware-1", etc.). Middleware are executed in the order they are registered.
+ *
+ * All middleware receive {@link MiddlewareContext} containing action type, blocker ID,
+ * configuration, and timestamp for each blocking event.
  *
- * This is a convenience function that registers multiple middleware at once.
- * Each middleware will be registered with an auto-generated name based on its index.
+ * @param middlewares - Array of middleware functions to register. Functions are called
+ *                      in order for each blocking action (add, remove, update, etc.)
  *
- * @param middlewares - Array of middleware functions to register
+ * @example
+ * Basic usage with built-in middleware
+ * ```ts
+ * import { configureMiddleware, loggerMiddleware, createPerformanceMiddleware } from '@okyrychenko-dev/react-action-guard';
+ *
+ * configureMiddleware([
+ *   loggerMiddleware,
+ *   createPerformanceMiddleware({ threshold: 1000 })
+ * ]);
+ * ```
+ *
+ * @example
+ * With custom middleware
+ * ```ts
+ * const customMiddleware: Middleware = (context) => {
+ *   if (context.action === 'add') {
+ *     console.log(`Blocker added: ${context.blockerId}`);
+ *   }
+ * };
+ *
+ * configureMiddleware([
+ *   loggerMiddleware,
+ *   customMiddleware
+ * ]);
+ * ```
+ *
+ * @example
+ * Analytics integration
+ * ```ts
+ * import { configureMiddleware, createAnalyticsMiddleware } from '@okyrychenko-dev/react-action-guard';
  *
+ * configureMiddleware([
+ *   createAnalyticsMiddleware({
+ *     provider: 'google-analytics',
+ *     trackingId: 'GA-XXXXX'
+ *   })
+ * ]);
+ * ```
+ *
+ * @see {@link Middleware} for middleware function signature
+ * @see {@link loggerMiddleware} for built-in logging middleware
+ * @see {@link createAnalyticsMiddleware} for analytics tracking
+ * @see {@link createPerformanceMiddleware} for performance monitoring
+ *
+ * @public
+ * @since 0.6.0
  */
 declare function configureMiddleware(middlewares: ReadonlyArray<Middleware>): void;
 
-declare const loggerMiddleware: Middleware;
+/**
+ * Built-in middleware for logging all blocking actions to the console.
+ *
+ * Logs every blocker action (add, remove, update, timeout, clear) with emoji
+ * indicators and formatted data. Useful for debugging blocking behavior during
+ * development. Automatically disabled in production builds for performance.
+ *
+ * Output format: `[UIBlocking] 🔒 blocker-id {scope: "form", reason: "..."}`
+ *
+ * Emoji indicators:
+ * - 🔒 Add
+ * - 🔓 Remove
+ * - 🔄 Update
+ * - ⏰ Timeout
+ * - 🧹 Clear/ClearScope
+ *
+ * @example
+ * Register logger middleware
+ * ```ts
+ * import { configureMiddleware, loggerMiddleware } from '@okyrychenko-dev/react-action-guard';
+ *
+ * // Enable logging for all blocking actions
+ * configureMiddleware([loggerMiddleware]);
+ * ```
+ *
+ * @example
+ * Console output examples
+ * ```
+ * [UIBlocking] 🔒 save-form {scope: "form", reason: "Saving...", priority: 50}
+ * [UIBlocking] 🔄 save-form {scope: "form", reason: "Almost done..."}
+ * [UIBlocking] 🔓 save-form {reason: "Saving..."}
+ * [UIBlocking] ⏰ api-timeout {timeout: 30000}
+ * ```
+ *
+ * @example
+ * Production check pattern
+ * ```ts
+ * import { configureMiddleware, loggerMiddleware } from '@okyrychenko-dev/react-action-guard';
+ * const middlewares = [];
+ * if (process.env.NODE_ENV !== 'production') {
+ *   middlewares.push(loggerMiddleware);
+ * }
+ * configureMiddleware(middlewares);
+ * ```
+ *
+ * @see {@link configureMiddleware} for registering middleware
+ * @see {@link Middleware} for middleware function signature
+ * @see {@link MiddlewareContext} for available context data
+ *
+ * @public
+ * @since 0.6.0
+ */
+declare function loggerMiddleware(context: MiddlewareContext): void;
 
 interface PerformanceConfig {
     slowBlockThreshold?: number;
     onSlowBlock?: (blockerId: string, duration: number) => void;
 }
 
-declare const createPerformanceMiddleware: (config?: PerformanceConfig) => Middleware;
+/**
+ * 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.
+ *
+ * Automatically logs warnings to console for slow blocks and optionally invokes
+ * a callback for custom handling (e.g., error reporting, analytics).
+ *
+ * @param config - Performance monitoring configuration
+ * @param config.slowBlockThreshold - Duration in ms before considering a block "slow".
+ *                                     Defaults to 3000ms (3 seconds).
+ * @param config.onSlowBlock - Optional callback invoked when a slow block is detected.
+ *                             Receives blockerId and duration in milliseconds.
+ *
+ * @returns Middleware function for performance monitoring
+ *
+ * @example
+ * Basic usage with default threshold
+ * ```ts
+ * import { configureMiddleware, createPerformanceMiddleware } from '@okyrychenko-dev/react-action-guard';
+ *
+ * const performanceMiddleware = createPerformanceMiddleware();
+ *
+ * configureMiddleware([performanceMiddleware]);
+ * // Warns if any blocker lasts > 3 seconds
+ * ```
+ *
+ * @example
+ * Custom threshold and callback
+ * ```ts
+ * const performanceMiddleware = createPerformanceMiddleware({
+ *   slowBlockThreshold: 5000, // 5 seconds
+ *   onSlowBlock: (blockerId, duration) => {
+ *     console.error(`Blocker ${blockerId} took ${duration}ms`);
+ *
+ *     // Report to error tracking
+ *     Sentry.captureMessage('Slow UI Blocker', {
+ *       extra: { blockerId, duration }
+ *     });
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * With analytics integration
+ * ```ts
+ * const performanceMiddleware = createPerformanceMiddleware({
+ *   slowBlockThreshold: 2000,
+ *   onSlowBlock: (blockerId, duration) => {
+ *     // Track slow blocks in analytics
+ *     analytics.track('slow_blocker_detected', {
+ *       blocker_id: blockerId,
+ *       duration_ms: duration,
+ *       threshold_ms: 2000
+ *     });
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * Development vs Production
+ * ```ts
+ * const performanceMiddleware = createPerformanceMiddleware({
+ *   // Strict threshold in development
+ *   slowBlockThreshold: process.env.NODE_ENV === 'production' ? 5000 : 1000,
+ *   onSlowBlock: (blockerId, duration) => {
+ *     if (process.env.NODE_ENV === 'production') {
+ *       // Report to error service in production
+ *       errorService.log({ blockerId, duration });
+ *     } else {
+ *       // Detailed logging in development
+ *       console.table({ blockerId, duration });
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @see {@link PerformanceConfig} for configuration options
+ * @see {@link configureMiddleware} for registering middleware
+ *
+ * @public
+ * @since 0.6.0
+ */
+declare function createPerformanceMiddleware(config?: PerformanceConfig): Middleware;
 
 /**
- * Configuration for a blocker
+ * 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 BlockerConfig {
     scope?: string | ReadonlyArray<string>;
@@ -95,7 +501,16 @@ interface BlockerConfig {
     onTimeout?: (blockerId: string) => void;
 }
 /**
- * Stored blocker with all required fields
+ * Internal representation of a blocker with all fields populated.
+ *
+ * This is the stored format in the Map. All optional fields from {@link BlockerConfig}
+ * are converted to required fields with default values applied.
+ *
+ * @internal This type is primarily for internal use. Users should work with
+ *           {@link BlockerConfig} for configuration and {@link BlockerInfo} for
+ *           reading blocker data.
+ *
+ * @since 0.6.0
  */
 interface StoredBlocker {
     scope: string | ReadonlyArray<string>;
@@ -110,20 +525,70 @@ interface StoredBlocker {
     onTimeout?: (blockerId: string) => void;
 }
 /**
- * Blocker information including its ID
+ * Complete blocker information including its unique identifier.
+ *
+ * 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
+ * Accessing blocker info
+ * ```ts
+ * const blockers: BlockerInfo[] = store.getState().getBlockingInfo('form');
+ * blockers.forEach(blocker => {
+ *   console.log(`${blocker.id}: ${blocker.reason} (priority: ${blocker.priority})`);
+ * });
+ * ```
+ *
+ * @public
+ * @since 0.6.0
  */
 interface BlockerInfo extends StoredBlocker {
     id: string;
 }
 /**
- * Internal store state
+ * Internal state structure of the UI blocking store.
+ *
+ * Contains the core data structures for managing blockers and middleware.
+ * This state is combined with {@link UIBlockingStoreActions} to create the
+ * complete {@link UIBlockingStore} type.
+ *
+ * @internal
+ * @since 0.6.0
  */
 interface UIBlockingStoreState {
     activeBlockers: Map<string, StoredBlocker>;
     middlewares: Map<string, Middleware>;
 }
 /**
- * Store actions
+ * All available actions for managing UI blocking state.
+ *
+ * These methods allow adding, removing, updating blockers, checking blocking status,
+ * and managing middleware. Combined with {@link UIBlockingStoreState} to form
+ * the complete {@link UIBlockingStore} type.
+ *
+ * All actions are safe to call multiple times and handle edge cases gracefully.
+ *
+ * @example
+ * Using store actions directly
+ * ```ts
+ * import { uiBlockingStoreApi } from '@okyrychenko-dev/react-action-guard';
+ *
+ * // Add a blocker
+ * uiBlockingStoreApi.getState().addBlocker('my-blocker', {
+ *   scope: 'form',
+ *   reason: 'Processing...'
+ * });
+ *
+ * // Check if blocked
+ * const isBlocked = uiBlockingStoreApi.getState().isBlocked('form');
+ *
+ * // Remove blocker
+ * uiBlockingStoreApi.getState().removeBlocker('my-blocker');
+ * ```
+ *
+ * @public
+ * @since 0.6.0
  */
 interface UIBlockingStoreActions {
     addBlocker: (id: string, config?: BlockerConfig) => void;
@@ -138,7 +603,32 @@ interface UIBlockingStoreActions {
     runMiddlewares: (context: MiddlewareContext) => Promise<void>;
 }
 /**
- * Complete store type (state + actions)
+ * 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
+ * Using the complete store
+ * ```ts
+ * import { useUIBlockingStore } from '@okyrychenko-dev/react-action-guard';
+ *
+ * function MyComponent() {
+ *   const store = useUIBlockingStore();
+ *
+ *   // Access state
+ *   console.log(store.activeBlockers.size);
+ *
+ *   // Call actions
+ *   store.addBlocker('my-blocker', { scope: 'form' });
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ *
+ * @public
+ * @since 0.6.0
  */
 type UIBlockingStore = UIBlockingStoreState & UIBlockingStoreActions;
 
@@ -162,37 +652,159 @@ declare const useUIBlockingStore: {
 declare const uiBlockingStoreApi: zustand.StoreApi<UIBlockingStore>;
 
 /**
- * Hook to automatically add and remove a blocker based on component lifecycle
+ * Automatically manages a UI blocker based on component lifecycle.
+ *
+ * Creates a blocker that is automatically added when the condition is true
+ * and removed when the component unmounts or condition becomes false.
+ * Supports scoped blocking, priorities, timeouts, and works with both
+ * global store and isolated provider instances.
  *
- * Automatically adds a blocker when the component mounts (or when activated)
- * and removes it when the component unmounts (or when deactivated).
+ * @param blockerId - Unique identifier for this blocker. Must be unique within the scope.
+ * @param config - Configuration object for the blocker
+ * @param config.scope - Scope(s) to block. Can be a single scope string (e.g., "form", "navigation")
+ *                       or an array of scopes (e.g., ["form", "navigation"]). Defaults to "global".
+ * @param config.reason - Human-readable reason for blocking, displayed in DevTools and UI
+ * @param config.priority - Priority level (0-100). Higher priority blockers take precedence.
+ *                          Use 0-30 for low priority, 31-70 for medium, 71-100 for high priority.
+ * @param config.timeout - Auto-removal timeout in milliseconds. Blocker will be automatically
+ *                         removed after this duration. Use 0 or undefined for no timeout.
+ * @param config.onTimeout - Callback function invoked when the blocker times out
+ * @param isActive - When true, blocker is active; when false, blocker is removed.
+ *                   Defaults to true. Use this for conditional blocking.
  *
- * Supports both global store and context store (via UIBlockingProvider).
+ * @example
+ * Basic form submission blocking
+ * ```tsx
+ * function MyForm() {
+ *   const [isSubmitting, setIsSubmitting] = useState(false);
+ *
+ *   useBlocker('form-submit', {
+ *     scope: 'form',
+ *     reason: 'Submitting form...',
+ *     priority: 50,
+ *     timeout: 30000, // Auto-remove after 30 seconds
+ *     onTimeout: () => {
+ *       console.warn('Form submission timed out');
+ *       setIsSubmitting(false);
+ *     }
+ *   }, isSubmitting);
+ *
+ *   return <form onSubmit={handleSubmit}>...</form>;
+ * }
+ * ```
+ *
+ * @example
+ * Multiple scopes with high priority
+ * ```tsx
+ * useBlocker('critical-save', {
+ *   scope: ['form', 'navigation', 'actions'],
+ *   reason: 'Saving critical data...',
+ *   priority: 90,
+ * }, isSaving);
+ * ```
+ *
+ * @example
+ * Conditional blocking based on unsaved changes
+ * ```tsx
+ * function Editor() {
+ *   const [hasUnsavedChanges, setHasUnsavedChanges] = useState(false);
+ *
+ *   useBlocker('unsaved-changes', {
+ *     scope: 'navigation',
+ *     reason: 'You have unsaved changes',
+ *     priority: 80,
+ *   }, hasUnsavedChanges);
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
  *
- * @param blockerId - Unique identifier for the blocker
- * @param config - Blocker configuration (scope, reason, priority)
- * @param isActive - Whether the blocker is currently active (default: true)
+ * @see {@link useIsBlocked} to check if a scope is currently blocked
+ * @see {@link useBlockingInfo} to get detailed blocker information
+ * @see {@link useAsyncAction} for async operation wrapping with automatic blocking
+ * @see {@link useConfirmableBlocker} for blockers that require user confirmation
  *
+ * @public
+ * @since 0.6.0
  */
-declare const useBlocker: (blockerId: string, config: BlockerConfig, isActive?: boolean) => void;
+declare function useBlocker(blockerId: string, config: BlockerConfig, isActive?: boolean): void;
 
 /**
- * Hook to get detailed blocking information for a scope
+ * Gets detailed information about all active blockers for a specific scope.
  *
- * Returns an array of blocker information objects for the specified scope,
- * sorted by priority (highest first). Automatically re-renders when blockers change.
+ * Returns an array of blocker information objects, sorted by priority (highest first).
+ * Each blocker object contains id, reason, priority, and scope information.
+ * The hook automatically re-renders when blockers are added, removed, or updated.
  *
- * Uses a stable reference - only re-renders when the actual blocker list changes,
- * not on every store update.
+ * Uses memoization to provide a stable reference - only re-renders when the actual
+ * blocker list changes, not on every store update. This makes it efficient for
+ * rendering lists of blockers.
  *
- * Supports both global store and context store (via UIBlockingProvider).
+ * Works with both the global store and isolated provider instances (via UIBlockingProvider).
  *
- * @param scope - Scope to get blocking information for (default: "global")
- * @returns Array of blocker information objects, sorted by priority
+ * @param scope - Scope to get blocking information for. Defaults to "global" if not specified.
+ * @returns Array of {@link BlockerInfo} objects, sorted by priority (highest to lowest)
  *
+ * @example
+ * Display list of active blockers
+ * ```tsx
+ * function BlockerList() {
+ *   const blockers = useBlockingInfo('form');
+ *
+ *   if (blockers.length === 0) {
+ *     return <div>No active blockers</div>;
+ *   }
+ *
+ *   return (
+ *     <ul>
+ *       {blockers.map((blocker) => (
+ *         <li key={blocker.id}>
+ *           {blocker.reason} (Priority: {blocker.priority})
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Show highest priority blocker reason
+ * ```tsx
+ * function BlockingBanner() {
+ *   const blockers = useBlockingInfo('global');
+ *
+ *   // blockers are already sorted by priority (highest first)
+ *   const topBlocker = blockers[0];
+ *
+ *   if (!topBlocker) {
+ *     return null;
+ *   }
+ *
+ *   return <div className="banner">{topBlocker.reason}</div>;
+ * }
  * ```
+ *
+ * @example
+ * Count active blockers
+ * ```tsx
+ * function BlockerCount() {
+ *   const formBlockers = useBlockingInfo('form');
+ *   const navBlockers = useBlockingInfo('navigation');
+ *
+ *   const total = formBlockers.length + navBlockers.length;
+ *
+ *   return <div>{total} active blockers</div>;
+ * }
+ * ```
+ *
+ * @see {@link useIsBlocked} for a simple boolean check
+ * @see {@link useBlocker} to create blockers
+ * @see {@link BlockerInfo} for the structure of blocker information objects
+ *
+ * @public
+ * @since 0.6.0
  */
-declare const useBlockingInfo: (scope?: string) => ReadonlyArray<BlockerInfo>;
+declare function useBlockingInfo(scope?: string): ReadonlyArray<BlockerInfo>;
 
 /**
  * Configuration for conditional blocker hook.
@@ -212,18 +824,152 @@ interface ConditionalBlockerConfig<TState = unknown> extends Omit<BlockerConfig,
 }
 
 /**
- * Hook for conditional blocking based on a condition function.
+ * Blocks UI based on a dynamic condition that is periodically evaluated.
+ *
+ * Periodically checks a condition function and automatically adds or removes
+ * a blocker based on the result. Useful for blocking based on application state,
+ * network status, feature flags, or any other dynamic condition.
  *
- * Periodically checks a condition and blocks/unblocks based on the result.
- * The condition is evaluated at the specified interval (default 1000ms).
+ * The condition function receives optional state and returns a boolean.
+ * It's evaluated immediately on mount and then at the specified interval.
+ * The blocker is added/removed automatically as the condition changes.
  *
- * Supports both global store and context store (via UIBlockingProvider).
+ * Works with both the global store and isolated provider instances (via UIBlockingProvider).
  *
- * @param blockerId - Unique identifier for this blocker
- * @param config - Configuration including condition function and check interval
+ * @template TState - Type of the state object passed to the condition function
+ * @param blockerId - Unique identifier for this conditional blocker
+ * @param config - Configuration for conditional blocking
+ * @param config.condition - Function that returns true to block, false to unblock.
+ *                           Receives the `state` object as parameter.
+ * @param config.state - Optional state object passed to the condition function
+ * @param config.checkInterval - How often to check the condition in milliseconds.
+ *                               Defaults to 1000ms (1 second). Lower values mean
+ *                               more responsive blocking but higher CPU usage.
+ * @param config.scope - Scope(s) to block when condition is true
+ * @param config.reason - Reason for blocking (displayed to users)
+ * @param config.priority - Optional blocker priority (0-100)
  *
+ * @example
+ * Block based on network status
+ * ```tsx
+ * function OfflineBlocker() {
+ *   const [isOnline, setIsOnline] = useState(navigator.onLine);
+ *
+ *   useEffect(() => {
+ *     const handleOnline = () => setIsOnline(true);
+ *     const handleOffline = () => setIsOnline(false);
+ *
+ *     window.addEventListener('online', handleOnline);
+ *     window.addEventListener('offline', handleOffline);
+ *
+ *     return () => {
+ *       window.removeEventListener('online', handleOnline);
+ *       window.removeEventListener('offline', handleOffline);
+ *     };
+ *   }, []);
+ *
+ *   useConditionalBlocker('offline', {
+ *     condition: () => !isOnline,
+ *     state: { isOnline },
+ *     checkInterval: 500, // Check every 500ms
+ *     scope: 'global',
+ *     reason: 'No internet connection. Please check your network.',
+ *     priority: 95
+ *   });
+ *
+ *   return <App />;
+ * }
+ * ```
+ *
+ * @example
+ * Block based on feature flag
+ * ```tsx
+ * function FeatureFlagBlocker() {
+ *   const featureFlags = useFeatureFlags();
+ *
+ *   useConditionalBlocker('feature-disabled', {
+ *     condition: (state) => !state.featureFlags.newFeatureEnabled,
+ *     state: { featureFlags },
+ *     checkInterval: 5000, // Check every 5 seconds
+ *     scope: 'new-feature',
+ *     reason: 'This feature is currently disabled',
+ *     priority: 70
+ *   });
+ *
+ *   return <NewFeature />;
+ * }
+ * ```
+ *
+ * @example
+ * Block during API rate limit
+ * ```tsx
+ * function RateLimitBlocker() {
+ *   const [requestCount, setRequestCount] = useState(0);
+ *   const [resetTime, setResetTime] = useState<number | null>(null);
+ *
+ *   useConditionalBlocker('rate-limit', {
+ *     condition: (state) => {
+ *       if (!state.resetTime) {
+ *         return false;
+ *       }
+ *       return Date.now() < state.resetTime && state.requestCount >= 100;
+ *     },
+ *     state: { requestCount, resetTime },
+ *     checkInterval: 1000,
+ *     scope: 'api',
+ *     reason: 'API rate limit reached. Please wait.',
+ *     priority: 90
+ *   });
+ *
+ *   return <Dashboard />;
+ * }
+ * ```
+ *
+ * @example
+ * Block based on form validation
+ * ```tsx
+ * function FormValidationBlocker() {
+ *   const { formState } = useFormContext();
+ *
+ *   useConditionalBlocker('invalid-form', {
+ *     condition: (state) => !state.isValid && state.isDirty,
+ *     state: formState,
+ *     checkInterval: 500,
+ *     scope: 'form-submit',
+ *     reason: 'Please fix form errors before submitting',
+ *     priority: 60
+ *   });
+ *
+ *   return <Form />;
+ * }
+ * ```
+ *
+ * @example
+ * 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;
+ *   },
+ *   checkInterval: 30000, // Check every 30 seconds
+ *   scope: 'heavy-operations',
+ *   reason: 'Battery level too low for this operation',
+ *   priority: 80
+ * });
+ * ```
+ *
+ * @see {@link useBlocker} for simple conditional blocking with boolean
+ * @see {@link useScheduledBlocker} for time-based blocking
+ * @see {@link ConditionalBlockerConfig} for configuration options
+ *
+ * @public
+ * @since 0.6.0
  */
-declare const useConditionalBlocker: <TState = unknown>(blockerId: string, config: ConditionalBlockerConfig<TState>) => void;
+declare function useConditionalBlocker<TState = unknown>(blockerId: string, config: ConditionalBlockerConfig<TState>): void;
 
 /**
  * Configuration for the confirmation dialog
@@ -267,24 +1013,213 @@ interface UseConfirmableBlockerReturn {
 }
 
 /**
- * Hook for creating a confirmable action with blocking UI
+ * Creates a blocker that requires user confirmation before executing an action.
+ *
+ * Manages a confirmation dialog and blocking state for actions that need user approval.
+ * The blocker is active during both the confirmation dialog display and action execution.
+ *
+ * Workflow:
+ * 1. Call `execute()` to show confirmation dialog (blocker activated)
+ * 2. User confirms → `onConfirm` callback runs (blocker remains active)
+ * 3. Action completes → blocker removed
+ * 4. User cancels → blocker removed, optional `onCancel` callback runs
+ *
+ * Works with both the global store and isolated provider instances (via UIBlockingProvider).
+ *
+ * @param blockerId - Unique identifier for this confirmable blocker
+ * @param config - Configuration for the confirmable action
+ * @param config.confirmMessage - Message to display in the confirmation dialog
+ * @param config.confirmTitle - Optional dialog title (defaults to "Confirm Action")
+ * @param config.confirmButtonText - Optional confirm button text (defaults to "Confirm")
+ * @param config.cancelButtonText - Optional cancel button text (defaults to "Cancel")
+ * @param config.onConfirm - Async function to execute after user confirms
+ * @param config.onCancel - Optional callback when user cancels
+ * @param config.scope - Scope(s) to block during confirmation and execution
+ * @param config.reason - Optional custom blocking reason (defaults to confirmMessage)
+ * @param config.priority - Optional blocker priority (0-100)
+ *
+ * @returns Object containing:
+ * - `execute`: Function to trigger the confirmation dialog
+ * - `isDialogOpen`: Boolean indicating if confirmation dialog is visible
+ * - `isExecuting`: Boolean indicating if the confirmed action is executing
+ * - `confirmConfig`: Dialog configuration (title, message, button texts)
+ * - `onConfirm`: Function to call when user confirms
+ * - `onCancel`: Function to call when user cancels
+ *
+ * @example
+ * Delete confirmation with custom dialog
+ * ```tsx
+ * function DeleteButton({ itemId, itemName }) {
+ *   const confirmableDelete = useConfirmableBlocker('delete-item', {
+ *     confirmMessage: `Are you sure you want to delete "${itemName}"?`,
+ *     confirmTitle: 'Delete Item',
+ *     confirmButtonText: 'Delete',
+ *     cancelButtonText: 'Keep',
+ *     scope: ['form', 'navigation'],
+ *     priority: 80,
+ *     onConfirm: async () => {
+ *       await deleteItem(itemId);
+ *       showToast('Item deleted successfully');
+ *     },
+ *     onCancel: () => {
+ *       console.log('Delete cancelled');
+ *     }
+ *   });
  *
+ *   return (
+ *     <>
+ *       <button onClick={confirmableDelete.execute}>
+ *         Delete
+ *       </button>
+ *
+ *       {confirmableDelete.isDialogOpen && (
+ *         <ConfirmDialog
+ *           {...confirmableDelete.confirmConfig}
+ *           onConfirm={confirmableDelete.onConfirm}
+ *           onCancel={confirmableDelete.onCancel}
+ *           isLoading={confirmableDelete.isExecuting}
+ *         />
+ *       )}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Simple confirmation with default dialog
+ * ```tsx
+ * function LogoutButton() {
+ *   const confirmLogout = useConfirmableBlocker('logout', {
+ *     confirmMessage: 'Are you sure you want to log out?',
+ *     scope: 'global',
+ *     onConfirm: async () => {
+ *       await api.logout();
+ *       navigate('/login');
+ *     }
+ *   });
+ *
+ *   return (
+ *     <>
+ *       <button onClick={confirmLogout.execute}>Logout</button>
+ *
+ *       {confirmLogout.isDialogOpen && (
+ *         <Dialog
+ *           title={confirmLogout.confirmConfig.title}
+ *           message={confirmLogout.confirmConfig.message}
+ *           onConfirm={confirmLogout.onConfirm}
+ *           onCancel={confirmLogout.onCancel}
+ *         />
+ *       )}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * With loading state during execution
+ * ```tsx
+ * function SaveButton() {
+ *   const confirmSave = useConfirmableBlocker('save-changes', {
+ *     confirmMessage: 'Save all changes?',
+ *     scope: 'form',
+ *     onConfirm: async () => {
+ *       await saveAllChanges();
+ *     }
+ *   });
+ *
+ *   return (
+ *     <button
+ *       onClick={confirmSave.execute}
+ *       disabled={confirmSave.isExecuting}
+ *     >
+ *       {confirmSave.isExecuting ? 'Saving...' : 'Save All'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link useBlocker} for simple blocking without confirmation
+ * @see {@link ConfirmableBlockerConfig} for configuration options
+ * @see {@link UseConfirmableBlockerReturn} for return value structure
+ *
+ * @public
+ * @since 0.6.0
  */
-declare const useConfirmableBlocker: (blockerId: string, config: ConfirmableBlockerConfig) => UseConfirmableBlockerReturn;
+declare function useConfirmableBlocker(blockerId: string, config: ConfirmableBlockerConfig): UseConfirmableBlockerReturn;
 
 /**
- * Hook to check if a scope is currently blocked
+ * Checks if one or more scopes are currently blocked.
+ *
+ * Returns a boolean indicating whether any of the specified scopes have active blockers.
+ * The hook automatically re-renders the component when the blocking state changes,
+ * ensuring your UI always reflects the current blocking state.
+ *
+ * Works with both the global store and isolated provider instances (via UIBlockingProvider).
+ *
+ * @param scope - Scope(s) to check for blocking. Can be:
+ *                - A single scope string (e.g., "form", "navigation", "global")
+ *                - An array of scopes (e.g., ["form", "navigation"])
+ *                - undefined to check the "global" scope
+ * @returns true if ANY of the specified scopes are blocked, false otherwise
+ *
+ * @example
+ * Basic single scope check
+ * ```tsx
+ * function SubmitButton() {
+ *   const isFormBlocked = useIsBlocked('form');
  *
- * Returns a boolean indicating whether the specified scope(s) are blocked.
- * Automatically re-renders when the blocking state changes.
+ *   return (
+ *     <button disabled={isFormBlocked}>
+ *       {isFormBlocked ? 'Processing...' : 'Submit'}
+ *     </button>
+ *   );
+ * }
+ * ```
  *
- * Supports both global store and context store (via UIBlockingProvider).
+ * @example
+ * Multiple scopes check
+ * ```tsx
+ * function NavigationLink({ href, children }) {
+ *   const isBlocked = useIsBlocked(['navigation', 'global']);
+ *
+ *   return (
+ *     <a
+ *       href={href}
+ *       onClick={(e) => {
+ *         if (isBlocked) {
+ *           e.preventDefault();
+ *           alert('Navigation is currently blocked');
+ *         }
+ *       }}
+ *       style={{ opacity: isBlocked ? 0.5 : 1 }}
+ *     >
+ *       {children}
+ *     </a>
+ *   );
+ * }
+ * ```
  *
- * @param scope - Scope or array of scopes to check (default: "global")
- * @returns True if any of the specified scopes are blocked
+ * @example
+ * Conditional rendering based on blocking state
+ * ```tsx
+ * function SaveIndicator() {
+ *   const isSaving = useIsBlocked('save');
+ *
+ *   if (!isSaving) {
+ *     return null;
+ *   }
+ *
+ *   return <div className="spinner">Saving...</div>;
+ * }
+ * ```
  *
+ * @see {@link useBlocker} to create a blocker
+ * @see {@link useBlockingInfo} to get detailed information about active blockers
+ *
+ * @public
+ * @since 0.6.0
  */
-declare const useIsBlocked: (scope?: string | ReadonlyArray<string>) => boolean;
+declare function useIsBlocked(scope?: string | ReadonlyArray<string>): boolean;
 
 /**
  * Schedule configuration for time-based blocking.
@@ -316,19 +1251,127 @@ interface ScheduledBlockerConfig extends BlockerConfig {
 }
 
 /**
- * Hook for scheduling UI blocking for a specific time period.
+ * Schedules UI blocking for a specific time period (e.g., maintenance windows).
+ *
+ * Automatically blocks UI between specified start and end times. Useful for
+ * scheduled maintenance, planned downtime, or time-based feature restrictions.
+ * Supports callbacks when the blocking period starts and ends.
+ *
+ * Time specifications support:
+ * - Date objects
+ * - ISO 8601 strings (e.g., "2024-01-15T10:00:00Z")
+ * - Unix timestamps (milliseconds since epoch)
+ *
+ * You can specify the end time either as an absolute time or as a duration
+ * from the start time. If both are provided, duration takes precedence.
+ *
+ * Works with both the global store and isolated provider instances (via UIBlockingProvider).
+ *
+ * @param blockerId - Unique identifier for this scheduled blocker
+ * @param config - Schedule configuration
+ * @param config.schedule - Schedule timing configuration
+ * @param config.schedule.start - When to start blocking (Date, ISO string, or timestamp)
+ * @param config.schedule.end - Optional absolute end time (Date, ISO string, or timestamp)
+ * @param config.schedule.duration - Optional duration in milliseconds from start time
+ * @param config.scope - Scope(s) to block during the scheduled period
+ * @param config.reason - Reason for blocking (displayed to users)
+ * @param config.priority - Optional blocker priority (0-100)
+ * @param config.onScheduleStart - Optional callback when blocking period starts
+ * @param config.onScheduleEnd - Optional callback when blocking period ends
+ *
+ * @example
+ * Maintenance window with absolute times
+ * ```tsx
+ * function MaintenanceWarning() {
+ *   useScheduledBlocker('maintenance', {
+ *     schedule: {
+ *       start: new Date('2024-01-15T02:00:00Z'),
+ *       end: new Date('2024-01-15T04:00:00Z'),
+ *     },
+ *     scope: 'global',
+ *     reason: 'System maintenance in progress',
+ *     priority: 95,
+ *     onScheduleStart: () => {
+ *       console.log('Maintenance started');
+ *       showNotification('System is now in maintenance mode');
+ *     },
+ *     onScheduleEnd: () => {
+ *       console.log('Maintenance completed');
+ *       showNotification('System is back online');
+ *     }
+ *   });
  *
- * Blocks UI during a scheduled maintenance window or time period.
- * Supports start/end times as Date objects, ISO strings, or timestamps.
- * If both duration and end are provided, duration takes precedence.
+ *   return <div>...</div>;
+ * }
+ * ```
  *
- * Supports both global store and context store (via UIBlockingProvider).
+ * @example
+ * Short maintenance with duration
+ * ```tsx
+ * useScheduledBlocker('quick-maintenance', {
+ *   schedule: {
+ *     start: new Date('2024-01-15T03:00:00'),
+ *     duration: 15 * 60 * 1000, // 15 minutes
+ *   },
+ *   scope: ['api', 'forms'],
+ *   reason: 'Brief system update',
+ *   priority: 90
+ * });
+ * ```
+ *
+ * @example
+ * Business hours enforcement
+ * ```tsx
+ * function BusinessHoursBlocker() {
+ *   const now = new Date();
+ *   const tomorrow9AM = new Date(now);
+ *   tomorrow9AM.setDate(now.getDate() + 1);
+ *   tomorrow9AM.setHours(9, 0, 0, 0);
  *
- * @param blockerId - Unique identifier for this blocker
- * @param config - Configuration including schedule and callbacks
+ *   useScheduledBlocker('after-hours', {
+ *     schedule: {
+ *       start: new Date(now.getTime() + 1000), // Start immediately
+ *       end: tomorrow9AM,
+ *     },
+ *     scope: 'trading',
+ *     reason: 'Trading is only available during business hours (9 AM - 5 PM)',
+ *     priority: 85
+ *   });
  *
+ *   return <TradingDashboard />;
+ * }
+ * ```
+ *
+ * @example
+ * Using ISO strings for scheduling
+ * ```tsx
+ * useScheduledBlocker('deployment', {
+ *   schedule: {
+ *     start: '2024-01-20T00:00:00Z',
+ *     duration: 2 * 60 * 60 * 1000, // 2 hours
+ *   },
+ *   scope: 'global',
+ *   reason: 'Deploying new version',
+ *   priority: 100,
+ *   onScheduleStart: () => {
+ *     analytics.track('deployment_started');
+ *   },
+ *   onScheduleEnd: () => {
+ *     analytics.track('deployment_completed');
+ *     window.location.reload(); // Reload to get new version
+ *   }
+ * });
+ * ```
+ *
+ * @see {@link useBlocker} for immediate blocking without scheduling
+ * @see {@link useConditionalBlocker} for condition-based blocking
+ * @see {@link ScheduledBlockerConfig} for configuration options
+ * @see {@link BlockingSchedule} for schedule specification details
+ *
+ * @public
+ * @since 0.6.0
  */
-declare const useScheduledBlocker: (blockerId: string, config: ScheduledBlockerConfig) => void;
+declare function useScheduledBlocker(blockerId: string, config: ScheduledBlockerConfig): void;
 
 /**
  * Default scope type
@@ -399,7 +1442,14 @@ interface TypedHooks<TScope extends string> {
 declare function createTypedHooks<TScope extends string>(): TypedHooks<TScope>;
 
 /**
- * Props for UIBlockingProvider component
+ * 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
  */
 interface UIBlockingProviderProps {
     children: ReactNode;
@@ -411,8 +1461,8 @@ interface UIBlockingProviderProps {
     middlewares?: ReadonlyArray<Middleware>;
 }
 /**
- * Base provider created using toolkit's createStoreProvider
- * This creates isolated store instances for SSR, testing, and micro-frontends
+ * Base provider implementation created using toolkit's createStoreProvider.
+ * @internal
  */
 declare const useUIBlockingContext: () => StoreApi<UIBlockingStore>;
 declare const useUIBlockingStoreFromContext: {
@@ -421,10 +1471,100 @@ declare const useUIBlockingStoreFromContext: {
 };
 declare const useIsInsideUIBlockingProvider: () => boolean;
 /**
- * Provider component for isolated UI blocking state
+ * 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
  *
- * Uses toolkit's createStoreProvider with built-in DevTools support
- * and onStoreCreate callback for middleware registration.
+ * @public
+ * @since 0.6.0
  */
 declare function UIBlockingProvider({ children, enableDevtools, devtoolsName, middlewares, }: UIBlockingProviderProps): ReactNode;