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

package/README.md

@@ -36,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 || ^19.0.0
-- [Zustand](https://zustand-demo.pmnd.rs/) ^4.5.7 || ^5.0.0 - State management library
+- [React](https://react.dev/) ^18.0.0 || ^19.0.0
+- [Zustand](https://zustand-demo.pmnd.rs/) ^5.0.0 - State management library
 
 ## Quick Start
 

package/dist/index.cjs

@@ -24,16 +24,18 @@ function normalizeScopeToArray(scope) {
 }
 
 // src/store/uiBlockingStore.actions.ts
-var normalizePriority = (priority, fallback = DEFAULT_PRIORITY) => {
+function normalizePriority(priority, fallback = DEFAULT_PRIORITY) {
   return priority !== void 0 ? Math.max(0, priority) : fallback;
-};
-var createMiddlewareContext = (action, blockerId, config, prevState) => ({
-  action,
-  blockerId,
-  config,
-  timestamp: Date.now(),
-  ...prevState && { prevState }
-});
+}
+function createMiddlewareContext(action, blockerId, config, prevState) {
+  return {
+    action,
+    blockerId,
+    config,
+    timestamp: Date.now(),
+    ...prevState && { prevState }
+  };
+}
 var createUIBlockingActions = (set, get) => ({
   // State
   activeBlockers: /* @__PURE__ */ new Map(),
@@ -64,11 +66,38 @@ var createUIBlockingActions = (set, get) => ({
   },
   // Actions
   /**
-   * Add a blocker to the store
+   * Adds a new blocker or overwrites an existing one.
+   *
+   * If a blocker with the same ID already exists, it will be replaced and any
+   * existing timeout will be cleared. The blocker is active immediately after
+   * being added. Triggers middleware with 'add' action.
+   *
+   * @param id - Unique identifier for the blocker. Must be unique within the store.
+   * @param config - Blocker configuration. All fields are optional with defaults applied.
    *
-   * @param id - Unique blocker identifier
-   * @param config - Optional blocker configuration
+   * @example
+   * Basic usage
+   * ```ts
+   * store.getState().addBlocker('save-operation', {
+   *   scope: 'form',
+   *   reason: 'Saving data...',
+   *   priority: 70
+   * });
+   * ```
    *
+   * @example
+   * With timeout
+   * ```ts
+   * store.getState().addBlocker('api-call', {
+   *   scope: 'global',
+   *   reason: 'Loading...',
+   *   timeout: 30000, // Auto-remove after 30 seconds
+   *   onTimeout: (id) => console.warn(`${id} timed out`)
+   * });
+   * ```
+   *
+   * @see {@link removeBlocker} to remove a blocker
+   * @see {@link updateBlocker} to update an existing blocker
    */
   addBlocker: (id, config = {}) => {
     const existingBlocker = get().activeBlockers.get(id);
@@ -116,11 +145,31 @@ var createUIBlockingActions = (set, get) => ({
     );
   },
   /**
-   * Update blocker metadata. If timeout is updated, the timer will be restarted.
+   * Updates an existing blocker or creates it if it doesn't exist.
+   *
+   * Merges the provided configuration with existing blocker data. If the timeout
+   * is changed, the timeout timer is restarted. Triggers middleware with 'update' action.
+   *
+   * @param id - Identifier of the blocker to update
+   * @param config - Partial configuration to merge with existing blocker data
    *
-   * @param id - Unique blocker identifier
-   * @param config - Partial blocker configuration to merge
+   * @example
+   * Update blocker reason
+   * ```ts
+   * store.getState().updateBlocker('save', {
+   *   reason: 'Saving additional data...'
+   * });
+   * ```
    *
+   * @example
+   * Extend timeout
+   * ```ts
+   * store.getState().updateBlocker('api-call', {
+   *   timeout: 60000 // Extend to 60 seconds
+   * });
+   * ```
+   *
+   * @see {@link addBlocker} to create a new blocker
    */
   updateBlocker: (id, config = {}) => {
     const existingBlocker = get().activeBlockers.get(id);
@@ -194,10 +243,23 @@ var createUIBlockingActions = (set, get) => ({
     );
   },
   /**
-   * Remove a blocker from the store
+   * Removes a blocker from the store.
+   *
+   * Clears any associated timeout and triggers middleware with 'remove' action.
+   * Safe to call even if the blocker doesn't exist (no-op in that case).
    *
-   * @param id - Blocker identifier to remove
+   * @param id - Identifier of the blocker to remove
    *
+   * @example
+   * ```ts
+   * // Add and remove a blocker
+   * store.getState().addBlocker('temp', { scope: 'form' });
+   * // ... later
+   * store.getState().removeBlocker('temp');
+   * ```
+   *
+   * @see {@link addBlocker} to add a blocker
+   * @see {@link clearAllBlockers} to remove all blockers at once
    */
   removeBlocker: (id) => {
     const prevBlocker = get().activeBlockers.get(id);
@@ -214,11 +276,30 @@ var createUIBlockingActions = (set, get) => ({
     }
   },
   /**
-   * Check if a scope is currently blocked
+   * Checks if one or more scopes are currently blocked.
+   *
+   * Returns true if ANY blocker affects the specified scope(s). Global scope
+   * blockers will cause this to return true for any scope check.
+   *
+   * @param scope - Scope(s) to check. Defaults to "global" if not specified.
+   *                Can be a single scope string or array of scopes.
+   * @returns true if any of the specified scopes are currently blocked
+   *
+   * @example
+   * Single scope check
+   * ```ts
+   * const isFormBlocked = store.getState().isBlocked('form');
+   * console.log(isFormBlocked); // true or false
+   * ```
    *
-   * @param scope - Scope or array of scopes to check (default: "global")
-   * @returns True if any of the scopes are blocked
+   * @example
+   * Multiple scopes check
+   * ```ts
+   * const isBlocked = store.getState().isBlocked(['form', 'navigation']);
+   * // Returns true if either 'form' OR 'navigation' has active blockers
+   * ```
    *
+   * @see {@link getBlockingInfo} for detailed blocker information
    */
   isBlocked: (scope = DEFAULT_SCOPE) => {
     const { activeBlockers } = get();
@@ -235,11 +316,37 @@ var createUIBlockingActions = (set, get) => ({
     return false;
   },
   /**
-   * Get detailed blocking information for a specific scope
+   * Gets detailed information about all blockers affecting a specific scope.
+   *
+   * Returns an array of blocker objects sorted by priority (highest first).
+   * Includes global blockers and scope-specific blockers. Each blocker object
+   * contains id, reason, priority, scope, timestamp, and timeout information.
    *
    * @param scope - Scope to get blocking information for
-   * @returns Array of blockers affecting the scope, sorted by priority (highest first)
+   * @returns Array of {@link BlockerInfo} objects, sorted by priority descending
+   *
+   * @example
+   * Display blocker details
+   * ```ts
+   * const blockers = store.getState().getBlockingInfo('form');
+   * blockers.forEach(blocker => {
+   *   console.log(`${blocker.id}: ${blocker.reason}`);
+   *   console.log(`Priority: ${blocker.priority}`);
+   * });
+   * ```
+   *
+   * @example
+   * Get highest priority blocker
+   * ```ts
+   * const blockers = store.getState().getBlockingInfo('navigation');
+   * const topBlocker = blockers[0]; // Highest priority
+   * if (topBlocker) {
+   *   console.log(`Top blocker: ${topBlocker.reason}`);
+   * }
+   * ```
    *
+   * @see {@link isBlocked} for a simple boolean check
+   * @see {@link BlockerInfo} for the structure of returned objects
    */
   getBlockingInfo: (scope) => {
     const { activeBlockers } = get();
@@ -253,7 +360,18 @@ var createUIBlockingActions = (set, get) => ({
     return blockers.sort((a, b) => b.priority - a.priority);
   },
   /**
-   * Clear all blockers from the store
+   * Removes all active blockers from the store.
+   *
+   * Clears all timeouts and triggers middleware with 'clear' action.
+   * Useful for resetting the blocking state.
+   *
+   * @example
+   * ```ts
+   * // Clear all blockers on logout
+   * store.getState().clearAllBlockers();
+   * ```
+   *
+   * @see {@link clearBlockersForScope} to clear blockers for a specific scope
    */
   clearAllBlockers: () => {
     const { activeBlockers } = get();
@@ -274,10 +392,28 @@ var createUIBlockingActions = (set, get) => ({
     }
   },
   /**
-   * Clear all blockers for a specific scope
+   * Removes all blockers that affect a specific scope.
+   *
+   * Clears timeouts for removed blockers and triggers middleware with
+   * 'clear_scope' action. Global scope blockers are NOT cleared by this method.
    *
    * @param scope - Scope to clear blockers for
    *
+   * @example
+   * Clear form blockers
+   * ```ts
+   * // Clear all blockers affecting 'form' scope
+   * store.getState().clearBlockersForScope('form');
+   * ```
+   *
+   * @example
+   * Clear on navigation
+   * ```ts
+   * // Clear navigation blockers when user navigates away
+   * store.getState().clearBlockersForScope('navigation');
+   * ```
+   *
+   * @see {@link clearAllBlockers} to clear all blockers
    */
   clearBlockersForScope: (scope) => {
     const { activeBlockers } = get();
@@ -364,7 +500,7 @@ function useResolvedStoreWithSelector(selector) {
 }
 
 // src/hooks/useAsyncAction/useAsyncAction.ts
-var useAsyncAction = (actionId, scope, options) => {
+function useAsyncAction(actionId, scope, options) {
   const { addBlocker, removeBlocker } = useResolvedStoreWithSelector((state) => ({
     addBlocker: state.addBlocker,
     removeBlocker: state.removeBlocker
@@ -390,8 +526,8 @@ var useAsyncAction = (actionId, scope, options) => {
     [actionId, scope, options?.timeout, options?.onTimeout, addBlocker, removeBlocker]
   );
   return executeWithBlocking;
-};
-var useBlocker = (blockerId, config, isActive = true) => {
+}
+function useBlocker(blockerId, config, isActive = true) {
   const { addBlocker, removeBlocker } = useResolvedStoreWithSelector((state) => ({
     addBlocker: state.addBlocker,
     removeBlocker: state.removeBlocker
@@ -405,7 +541,7 @@ var useBlocker = (blockerId, config, isActive = true) => {
       removeBlocker(blockerId);
     };
   }, [blockerId, isActive, addBlocker, removeBlocker]);
-};
+}
 
 // src/hooks/useBlocker/useBlocker.utils.ts
 function createBlockerConfig(config) {
@@ -415,13 +551,13 @@ function createBlockerConfig(config) {
     priority: config.priority
   };
 }
-var useBlockingInfo = (scope = DEFAULT_SCOPE) => {
+function useBlockingInfo(scope = DEFAULT_SCOPE) {
   const store = useResolvedStore();
   const activeBlockers = zustand.useStore(store, (state) => state.activeBlockers);
   return react.useMemo(() => {
     return store.getState().getBlockingInfo(scope);
   }, [activeBlockers, scope, store]);
-};
+}
 function useConfigRef(config) {
   const configRef = react.useRef(config);
   react.useEffect(() => {
@@ -431,7 +567,7 @@ function useConfigRef(config) {
 }
 
 // src/hooks/useConditionalBlocker/useConditionalBlocker.ts
-var useConditionalBlocker = (blockerId, config) => {
+function useConditionalBlocker(blockerId, config) {
   const { addBlocker, removeBlocker } = useResolvedStoreWithSelector((state) => ({
     addBlocker: state.addBlocker,
     removeBlocker: state.removeBlocker
@@ -467,8 +603,8 @@ var useConditionalBlocker = (blockerId, config) => {
       }
     };
   }, [checkCondition, blockerId, removeBlocker]);
-};
-var useConfirmableBlocker = (blockerId, config) => {
+}
+function useConfirmableBlocker(blockerId, config) {
   const [isDialogOpen, setIsDialogOpen] = react.useState(false);
   const [isExecuting, setIsExecuting] = react.useState(false);
   useBlocker(
@@ -511,12 +647,12 @@ var useConfirmableBlocker = (blockerId, config) => {
     onConfirm,
     onCancel
   };
-};
+}
 
 // src/hooks/useIsBlocked/useIsBlocked.ts
-var useIsBlocked = (scope) => {
+function useIsBlocked(scope) {
   return useResolvedStoreWithSelector((state) => state.isBlocked(scope));
-};
+}
 
 // src/hooks/useScheduledBlocker/useScheduledBlocker.utils.ts
 var MAX_TIMEOUT_MS = 2147483647;
@@ -556,7 +692,7 @@ function isScheduleInPast(startTime, endTime, now) {
 }
 
 // src/hooks/useScheduledBlocker/useScheduledBlocker.ts
-var useScheduledBlocker = (blockerId, config) => {
+function useScheduledBlocker(blockerId, config) {
   const { addBlocker, removeBlocker } = useResolvedStoreWithSelector((state) => ({
     addBlocker: state.addBlocker,
     removeBlocker: state.removeBlocker
@@ -622,13 +758,13 @@ var useScheduledBlocker = (blockerId, config) => {
       removeBlocker(blockerId);
     };
   }, [blockerId, addBlocker, removeBlocker, cleanup]);
-};
+}
 
 // src/middleware/analyticsMiddleware.utils.ts
-var capitalizeFirst = (str) => {
+function capitalizeFirst(str) {
   return str.charAt(0).toUpperCase() + str.slice(1);
-};
-var buildEventData = (context) => {
+}
+function buildEventData(context) {
   const eventData = {
     blocker_id: context.blockerId
   };
@@ -643,33 +779,33 @@ var buildEventData = (context) => {
     eventData.priority = priority;
   }
   return eventData;
-};
-var trackGoogleAnalytics = (action, eventData) => {
+}
+function trackGoogleAnalytics(action, eventData) {
   if (window.gtag) {
     window.gtag("event", `ui_blocking_${action}`, eventData);
   }
-};
-var trackMixpanel = (action, eventData) => {
+}
+function trackMixpanel(action, eventData) {
   if (window.mixpanel) {
     const eventName = `UI Blocking ${action.split("_").map(capitalizeFirst).join(" ")}`;
     window.mixpanel.track(eventName, eventData);
   }
-};
-var trackAmplitude = (action, eventData) => {
+}
+function trackAmplitude(action, eventData) {
   if (window.amplitude) {
     const eventName = `UI Blocking ${action.split("_").map(capitalizeFirst).join(" ")}`;
     window.amplitude.track(eventName, eventData);
   }
-};
-var trackCustom = (trackFn, action, eventData) => {
+}
+function trackCustom(trackFn, action, eventData) {
   try {
     trackFn(`ui_blocking_${action}`, eventData);
   } catch {
   }
-};
+}
 
 // src/middleware/analyticsMiddleware.ts
-var trackEvent = (config, context, eventData) => {
+function trackEvent(config, context, eventData) {
   if ("provider" in config) {
     switch (config.provider) {
       case "ga":
@@ -686,13 +822,13 @@ var trackEvent = (config, context, eventData) => {
   if ("track" in config) {
     trackCustom(config.track, context.action, eventData);
   }
-};
-var createAnalyticsMiddleware = (config) => {
+}
+function createAnalyticsMiddleware(config) {
   return (context) => {
     const eventData = buildEventData(context);
     trackEvent(config, context, eventData);
   };
-};
+}
 
 // src/middleware/configureMiddleware.ts
 function configureMiddleware(middlewares) {
@@ -704,7 +840,7 @@ function configureMiddleware(middlewares) {
 }
 
 // src/middleware/loggerMiddleware.utils.ts
-var getActionEmoji = (action) => {
+function getActionEmoji(action) {
   switch (action) {
     case "add":
       return "\u2795";
@@ -721,8 +857,8 @@ var getActionEmoji = (action) => {
     default:
       return "\u2753";
   }
-};
-var extractConfigDetails = (config) => {
+}
+function extractConfigDetails(config) {
   if (!config) {
     return {};
   }
@@ -735,8 +871,8 @@ var extractConfigDetails = (config) => {
     details.priority = priority;
   }
   return details;
-};
-var formatLogData = (context) => {
+}
+function formatLogData(context) {
   const configDetails = extractConfigDetails(context.config);
   const logData = {};
   if (context.scope !== void 0) {
@@ -755,26 +891,26 @@ var formatLogData = (context) => {
     return configDetails;
   }
   return Object.keys(logData).length === 1 && logData.config ? configDetails : logData;
-};
+}
 
 // src/middleware/loggerMiddleware.ts
 var LOG_PREFIX = "[UIBlocking]";
-var loggerMiddleware = (context) => {
+function loggerMiddleware(context) {
   const emoji = getActionEmoji(context.action);
   const logData = formatLogData(context);
   console.log(LOG_PREFIX, emoji, context.blockerId, logData);
-};
+}
 
 // src/middleware/performanceMiddleware.utils.ts
-var handleAddAction = (blockerId, timestamp, blockStartTimes) => {
+function handleAddAction(blockerId, timestamp, blockStartTimes) {
   blockStartTimes.set(blockerId, timestamp);
-};
+}
 
 // src/middleware/performanceMiddleware.ts
 var DEFAULT_SLOW_BLOCK_THRESHOLD = 3e3;
 var ACTION_ADD = "add";
 var ACTION_REMOVE = "remove";
-var handleRemoveAction = (context, blockStartTimes, slowBlockThreshold, onSlowBlock) => {
+function handleRemoveAction(context, blockStartTimes, slowBlockThreshold, onSlowBlock) {
   const startTime = blockStartTimes.get(context.blockerId);
   if (startTime === void 0) {
     return;
@@ -787,8 +923,8 @@ var handleRemoveAction = (context, blockStartTimes, slowBlockThreshold, onSlowBl
     );
     onSlowBlock?.(context.blockerId, duration);
   }
-};
-var createPerformanceMiddleware = (config = {}) => {
+}
+function createPerformanceMiddleware(config = {}) {
   const { slowBlockThreshold = DEFAULT_SLOW_BLOCK_THRESHOLD, onSlowBlock } = config;
   const blockStartTimes = /* @__PURE__ */ new Map();
   return (context) => {
@@ -798,7 +934,7 @@ var createPerformanceMiddleware = (config = {}) => {
       handleRemoveAction(context, blockStartTimes, slowBlockThreshold, onSlowBlock);
     }
   };
-};
+}
 
 // src/createTypedHooks.ts
 function createTypedHooks() {