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

package/dist/index.cjs

@@ -64,11 +64,38 @@ var createUIBlockingActions = (set, get) => ({
   },
   // Actions
   /**
-   * Add a blocker to the store
-   *
-   * @param id - Unique blocker identifier
-   * @param config - Optional blocker configuration
-   *
+   * 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.
+   * 
+   * @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 +143,31 @@ var createUIBlockingActions = (set, get) => ({
     );
   },
   /**
-   * Update blocker metadata. If timeout is updated, the timer will be restarted.
-   *
-   * @param id - Unique blocker identifier
-   * @param config - Partial blocker configuration to merge
-   *
+   * 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
+   * 
+   * @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 +241,23 @@ var createUIBlockingActions = (set, get) => ({
     );
   },
   /**
-   * Remove a blocker from the store
-   *
-   * @param id - Blocker identifier to remove
-   *
+   * 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 - 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 +274,30 @@ var createUIBlockingActions = (set, get) => ({
     }
   },
   /**
-   * Check if a scope is currently blocked
-   *
-   * @param scope - Scope or array of scopes to check (default: "global")
-   * @returns True if any of the scopes are 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
+   * ```
+   * 
+   * @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 +314,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 +358,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 +390,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();