@okyrychenko-dev/react-action-guard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Olexii Kyrychenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,242 @@
+# @okyrychenko-dev/react-action-guard
+
+> Elegant UI blocking management for React applications with priorities, scopes, and automatic cleanup
+
+## Features
+
+- Priority-based blocking system
+- Scoped blocking (global, specific areas, or multiple scopes)
+- Automatic cleanup on unmount
+- TypeScript support
+- Built on Zustand for efficient state management
+- Hooks-based API
+
+## Installation
+
+```bash
+npm install @okyrychenko-dev/react-action-guard zustand
+```
+
+## Quick Start
+
+```jsx
+import { useBlocker, useIsBlocked } from '@okyrychenko-dev/react-action-guard';
+
+function MyComponent() {
+  const isBlocked = useIsBlocked('my-scope');
+
+  return (
+    <button disabled={isBlocked}>
+      Click me
+    </button>
+  );
+}
+```
+
+## API Reference
+
+### Hooks
+
+#### `useBlocker(blockerId, config, isActive)`
+
+Automatically adds a blocker when the component mounts and removes it on unmount.
+
+**Parameters:**
+- `blockerId: string` - Unique identifier for the blocker
+- `config: BlockerConfig` - Configuration object
+  - `scope?: string | string[]` - Scope(s) to block (default: "global")
+  - `reason?: string` - Reason for blocking (for debugging)
+  - `priority?: number` - Priority level (higher = more important)
+- `isActive?: boolean` - Whether the blocker is active (default: true)
+
+**Example:**
+
+```jsx
+function MyComponent() {
+  useBlocker('my-blocker', {
+    scope: 'form',
+    reason: 'Form is saving',
+    priority: 10
+  });
+
+  return <div>Content</div>;
+}
+```
+
+#### `useIsBlocked(scope)`
+
+Checks if a specific scope (or scopes) is currently blocked.
+
+**Parameters:**
+- `scope?: string | string[]` - Scope(s) to check (default: "global")
+
+**Returns:** `boolean` - Whether the scope is blocked
+
+**Example:**
+
+```jsx
+function SubmitButton() {
+  const isFormBlocked = useIsBlocked('form');
+
+  return (
+    <button disabled={isFormBlocked}>
+      Submit
+    </button>
+  );
+}
+```
+
+#### `useAsyncAction(actionId, scope)`
+
+Wraps an async function with automatic blocking/unblocking.
+
+**Parameters:**
+- `actionId: string` - Identifier for the action
+- `scope?: string | string[]` - Scope(s) to block during execution
+
+**Returns:** `(asyncFn: () => Promise<T>) => Promise<T>` - Function wrapper
+
+**Example:**
+
+```jsx
+function MyComponent() {
+  const executeWithBlocking = useAsyncAction('save-data', 'form');
+
+  const handleSave = async () => {
+    await executeWithBlocking(async () => {
+      await saveData();
+    });
+  };
+
+  return <button onClick={handleSave}>Save</button>;
+}
+```
+
+### Store
+
+#### `useUIBlockingStore`
+
+Direct access to the Zustand store for advanced use cases.
+
+**Methods:**
+- `addBlocker(id, config)` - Manually add a blocker
+- `removeBlocker(id)` - Manually remove a blocker
+- `isBlocked(scope)` - Check if scope is blocked
+- `getBlockingInfo(scope)` - Get detailed blocking information
+- `clearAllBlockers()` - Remove all blockers
+- `clearBlockersForScope(scope)` - Remove blockers for specific scope
+
+**Example:**
+
+```jsx
+import { useUIBlockingStore } from '@okyrychenko-dev/react-action-guard';
+
+function AdvancedComponent() {
+  const { addBlocker, removeBlocker } = useUIBlockingStore();
+
+  const startBlocking = () => {
+    addBlocker('custom-blocker', {
+      scope: ['form', 'navigation'],
+      reason: 'Critical operation in progress',
+      priority: 100
+    });
+  };
+
+  const stopBlocking = () => {
+    removeBlocker('custom-blocker');
+  };
+
+  return (
+    <div>
+      <button onClick={startBlocking}>Start</button>
+      <button onClick={stopBlocking}>Stop</button>
+    </div>
+  );
+}
+```
+
+## TypeScript
+
+The package is written in TypeScript and includes full type definitions.
+
+```typescript
+import type {
+  BlockerConfig,
+  BlockerInfo,
+  UIBlockingState
+} from '@okyrychenko-dev/react-action-guard';
+```
+
+## Use Cases
+
+### Loading States
+
+```jsx
+function DataLoader() {
+  const [isLoading, setIsLoading] = useState(false);
+
+  useBlocker('data-loader', {
+    scope: 'content',
+    reason: 'Loading data'
+  }, isLoading);
+
+  // ... rest of component
+}
+```
+
+### Form Submission
+
+```jsx
+function UserForm() {
+  const executeWithBlocking = useAsyncAction('submit-form', 'form');
+  const isBlocked = useIsBlocked('form');
+
+  const handleSubmit = async (data) => {
+    await executeWithBlocking(async () => {
+      await submitForm(data);
+    });
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input disabled={isBlocked} />
+      <button disabled={isBlocked}>Submit</button>
+    </form>
+  );
+}
+```
+
+### Global Loading Overlay
+
+```jsx
+function App() {
+  const isGloballyBlocked = useIsBlocked('global');
+
+  return (
+    <div>
+      {isGloballyBlocked && <LoadingOverlay />}
+      <YourApp />
+    </div>
+  );
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Type checking
+npm run typecheck
+
+# Watch mode for development
+npm run dev
+```
+
+## License
+
+MIT © Oleksandr Kyrychenko

package/dist/index.cjs

@@ -0,0 +1,182 @@
+'use strict';
+
+var react = require('react');
+var zustand = require('zustand');
+var middleware = require('zustand/middleware');
+
+// src/hooks/useBlocker.ts
+
+// src/store/uiBlockingStore.constants.ts
+var DEFAULT_SCOPE = "global";
+var DEFAULT_REASON = "Unknown";
+var DEFAULT_PRIORITY = 0;
+var ASYNC_ACTION_PRIORITY = 20;
+var DEVTOOLS_NAME = "UIBlocking";
+
+// src/store/uiBlockingStore.utils.ts
+function normalizeScopeToArray(scope) {
+  if (typeof scope === "string") {
+    return [scope];
+  }
+  return Array.from(scope);
+}
+
+// src/store/uiBlockingStore.actions.ts
+var createUIBlockingActions = (set, get) => ({
+  // State
+  activeBlockers: /* @__PURE__ */ new Map(),
+  // Actions
+  /**
+   * Add a blocker to the store
+   *
+   * @param id - Unique blocker identifier
+   * @param config - Optional blocker configuration
+   *
+   */
+  addBlocker: (id, config = {}) => {
+    set((state) => {
+      const newBlockers = new Map(state.activeBlockers);
+      const storedBlocker = {
+        scope: config.scope ?? DEFAULT_SCOPE,
+        reason: config.reason ?? DEFAULT_REASON,
+        priority: config.priority ?? DEFAULT_PRIORITY,
+        timestamp: config.timestamp ?? Date.now()
+      };
+      newBlockers.set(id, storedBlocker);
+      return { activeBlockers: newBlockers };
+    });
+  },
+  /**
+   * Remove a blocker from the store
+   *
+   * @param id - Blocker identifier to remove
+   *
+   */
+  removeBlocker: (id) => {
+    set((state) => {
+      const newBlockers = new Map(state.activeBlockers);
+      newBlockers.delete(id);
+      return { activeBlockers: newBlockers };
+    });
+  },
+  /**
+   * 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
+   *
+   */
+  isBlocked: (scope = DEFAULT_SCOPE) => {
+    const { activeBlockers } = get();
+    const scopes = normalizeScopeToArray(scope);
+    for (const [, blocker] of activeBlockers) {
+      if (blocker.scope === DEFAULT_SCOPE) {
+        return true;
+      }
+      const blockerScopes = normalizeScopeToArray(blocker.scope);
+      if (scopes.some((s) => blockerScopes.includes(s))) {
+        return true;
+      }
+    }
+    return false;
+  },
+  /**
+   * Get detailed blocking information for a specific scope
+   *
+   * @param scope - Scope to get blocking information for
+   * @returns Array of blockers affecting the scope, sorted by priority (highest first)
+   *
+   */
+  getBlockingInfo: (scope) => {
+    const { activeBlockers } = get();
+    const blockers = [];
+    for (const [id, blocker] of activeBlockers) {
+      const blockerScopes = normalizeScopeToArray(blocker.scope);
+      if (blocker.scope === DEFAULT_SCOPE || blockerScopes.includes(scope)) {
+        blockers.push({ id, ...blocker });
+      }
+    }
+    return blockers.sort((a, b) => b.priority - a.priority);
+  },
+  /**
+   * Clear all blockers from the store
+   */
+  clearAllBlockers: () => {
+    set({ activeBlockers: /* @__PURE__ */ new Map() });
+  },
+  /**
+   * Clear all blockers for a specific scope
+   *
+   * @param scope - Scope to clear blockers for
+   *
+   */
+  clearBlockersForScope: (scope) => {
+    set((state) => {
+      const newBlockers = /* @__PURE__ */ new Map();
+      for (const [id, blocker] of state.activeBlockers) {
+        const blockerScopes = normalizeScopeToArray(blocker.scope);
+        if (!blockerScopes.includes(scope)) {
+          newBlockers.set(id, blocker);
+        }
+      }
+      return { activeBlockers: newBlockers };
+    });
+  }
+});
+
+// src/store/uiBlockingStore.config.ts
+var devtoolsConfig = {
+  name: DEVTOOLS_NAME,
+  enabled: process.env.NODE_ENV !== "production"
+};
+
+// src/store/uiBlockingStore.store.ts
+var useUIBlockingStore = zustand.create()(
+  middleware.devtools(createUIBlockingActions, devtoolsConfig)
+);
+
+// src/hooks/useBlocker.ts
+var useBlocker = (blockerId, config, isActive = true) => {
+  const { addBlocker, removeBlocker } = useUIBlockingStore();
+  react.useEffect(() => {
+    if (!isActive || !blockerId) {
+      return;
+    }
+    addBlocker(blockerId, config);
+    return () => {
+      removeBlocker(blockerId);
+    };
+  }, [blockerId, isActive, addBlocker, removeBlocker]);
+};
+
+// src/hooks/useIsBlocked.ts
+var useIsBlocked = (scope) => {
+  return useUIBlockingStore((state) => state.isBlocked(scope));
+};
+var useAsyncAction = (actionId, scope) => {
+  const { addBlocker, removeBlocker } = useUIBlockingStore();
+  const executeWithBlocking = react.useCallback(
+    async (asyncFn) => {
+      const blockerId = `${actionId}-${Date.now().toString()}`;
+      try {
+        addBlocker(blockerId, {
+          scope,
+          reason: `Executing ${actionId}`,
+          priority: ASYNC_ACTION_PRIORITY
+        });
+        return await asyncFn();
+      } finally {
+        removeBlocker(blockerId);
+      }
+    },
+    [actionId, scope, addBlocker, removeBlocker]
+  );
+  return executeWithBlocking;
+};
+
+exports.useAsyncAction = useAsyncAction;
+exports.useBlocker = useBlocker;
+exports.useIsBlocked = useIsBlocked;
+exports.useUIBlockingStore = useUIBlockingStore;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/store/uiBlockingStore.constants.ts","../src/store/uiBlockingStore.utils.ts","../src/store/uiBlockingStore.actions.ts","../src/store/uiBlockingStore.config.ts","../src/store/uiBlockingStore.store.ts","../src/hooks/useBlocker.ts","../src/hooks/useIsBlocked.ts","../src/hooks/useAsyncAction.ts"],"names":["create","devtools","useEffect","useCallback"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Default values and constants for UI Blocking Store\n */\n\n/**\n * Default scope for blockers\n */\nexport const DEFAULT_SCOPE = \"global\" as const;\n\n/**\n * Default reason when none is provided\n */\nexport const DEFAULT_REASON = \"Unknown\" as const;\n\n/**\n * Default priority for blockers\n */\nexport const DEFAULT_PRIORITY = 0 as const;\n\n/**\n * Default priority for async actions\n */\nexport const ASYNC_ACTION_PRIORITY = 20 as const;\n\n/**\n * DevTools store name\n */\nexport const DEVTOOLS_NAME = \"UIBlocking\" as const;\n","/**\n * Normalize scope to array format\n *\n * @param scope - Single scope or array of scopes\n * @returns Array of scopes\n *\n * @internal\n */\nexport function normalizeScopeToArray(scope: string | ReadonlyArray<string>): Array<string> {\n  if (typeof scope === \"string\") {\n    return [scope];\n  }\n  return Array.from(scope);\n}\n","import type { StateCreator } from \"zustand\";\nimport type {\n  BlockerConfig,\n  BlockerInfo,\n  StoredBlocker,\n  UIBlockingStore,\n} from \"./uiBlockingStore.types\";\nimport { DEFAULT_SCOPE, DEFAULT_REASON, DEFAULT_PRIORITY } from \"./uiBlockingStore.constants\";\nimport { normalizeScopeToArray } from \"./uiBlockingStore.utils\";\n\n/**\n * UI Blocking Store Slice\n *\n * Implements the state and actions for UI blocking management.\n * This slice follows the Zustand slice pattern for better code organization.\n */\nexport const createUIBlockingActions: StateCreator<UIBlockingStore, [], [], UIBlockingStore> = (\n  set,\n  get\n) => ({\n  // State\n  activeBlockers: new Map(),\n\n  // Actions\n  /**\n   * Add a blocker to the store\n   *\n   * @param id - Unique blocker identifier\n   * @param config - Optional blocker configuration\n   *\n   */\n  addBlocker: (id: string, config: BlockerConfig = {}): void => {\n    set((state) => {\n      const newBlockers = new Map(state.activeBlockers);\n      const storedBlocker: StoredBlocker = {\n        scope: config.scope ?? DEFAULT_SCOPE,\n        reason: config.reason ?? DEFAULT_REASON,\n        priority: config.priority ?? DEFAULT_PRIORITY,\n        timestamp: config.timestamp ?? Date.now(),\n      };\n      newBlockers.set(id, storedBlocker);\n\n      return { activeBlockers: newBlockers };\n    });\n  },\n\n  /**\n   * Remove a blocker from the store\n   *\n   * @param id - Blocker identifier to remove\n   *\n   */\n  removeBlocker: (id: string): void => {\n    set((state) => {\n      const newBlockers = new Map(state.activeBlockers);\n      newBlockers.delete(id);\n\n      return { activeBlockers: newBlockers };\n    });\n  },\n\n  /**\n   * Check if a scope is currently blocked\n   *\n   * @param scope - Scope or array of scopes to check (default: \"global\")\n   * @returns True if any of the scopes are blocked\n   *\n   */\n  isBlocked: (scope: string | ReadonlyArray<string> = DEFAULT_SCOPE): boolean => {\n    const { activeBlockers } = get();\n    const scopes = normalizeScopeToArray(scope);\n\n    for (const [, blocker] of activeBlockers) {\n      // Global blocking blocks everything\n      if (blocker.scope === DEFAULT_SCOPE) {\n        return true;\n      }\n\n      // Check scope intersection\n      const blockerScopes = normalizeScopeToArray(blocker.scope);\n\n      if (scopes.some((s) => blockerScopes.includes(s))) {\n        return true;\n      }\n    }\n\n    return false;\n  },\n\n  /**\n   * Get detailed blocking information for a specific scope\n   *\n   * @param scope - Scope to get blocking information for\n   * @returns Array of blockers affecting the scope, sorted by priority (highest first)\n   *\n   */\n  getBlockingInfo: (scope: string): ReadonlyArray<BlockerInfo> => {\n    const { activeBlockers } = get();\n    const blockers: Array<BlockerInfo> = [];\n\n    for (const [id, blocker] of activeBlockers) {\n      const blockerScopes = normalizeScopeToArray(blocker.scope);\n\n      if (blocker.scope === DEFAULT_SCOPE || blockerScopes.includes(scope)) {\n        blockers.push({ id, ...blocker });\n      }\n    }\n\n    return blockers.sort((a, b) => b.priority - a.priority);\n  },\n\n  /**\n   * Clear all blockers from the store\n   */\n  clearAllBlockers: (): void => {\n    set({ activeBlockers: new Map() });\n  },\n\n  /**\n   * Clear all blockers for a specific scope\n   *\n   * @param scope - Scope to clear blockers for\n   *\n   */\n  clearBlockersForScope: (scope: string): void => {\n    set((state) => {\n      const newBlockers = new Map();\n\n      for (const [id, blocker] of state.activeBlockers) {\n        const blockerScopes = normalizeScopeToArray(blocker.scope);\n\n        if (!blockerScopes.includes(scope)) {\n          newBlockers.set(id, blocker);\n        }\n      }\n\n      return { activeBlockers: newBlockers };\n    });\n  },\n});\n","import type { DevtoolsOptions } from \"zustand/middleware\";\nimport { DEVTOOLS_NAME } from \"./uiBlockingStore.constants\";\n\n/**\n * DevTools configuration for UI Blocking Store\n *\n * Enables Redux DevTools integration only in development mode\n * for better debugging experience without production overhead.\n */\nexport const devtoolsConfig: DevtoolsOptions = {\n  name: DEVTOOLS_NAME,\n  enabled: process.env.NODE_ENV !== \"production\",\n};\n","import { create } from \"zustand\";\nimport { devtools } from \"zustand/middleware\";\nimport { createUIBlockingActions } from \"./uiBlockingStore.actions\";\nimport { devtoolsConfig } from \"./uiBlockingStore.config\";\nimport type { UIBlockingStore } from \"./uiBlockingStore.types\";\n\n/**\n * UI Blocking Store\n *\n * Global Zustand store for managing UI blocking state across the application.\n *\n * Features:\n * - Priority-based blocking system\n * - Scope-based blocking (global, specific areas, or multiple scopes)\n * - Automatic cleanup on unmount (when using hooks)\n * - DevTools integration for debugging\n *\n */\nexport const useUIBlockingStore = create<UIBlockingStore>()(\n  devtools(createUIBlockingActions, devtoolsConfig)\n);\n","import { useEffect } from \"react\";\nimport { useUIBlockingStore } from \"../store\";\nimport type { BlockerConfig } from \"../store\";\n\n/**\n * Hook to automatically add and remove a blocker based on component lifecycle\n *\n * Automatically adds a blocker when the component mounts (or when activated)\n * and removes it when the component unmounts (or when deactivated).\n *\n * @param blockerId - Unique identifier for the blocker\n * @param config - Blocker configuration (scope, reason, priority)\n * @param isActive - Whether the blocker is currently active (default: true)\n *\n */\nexport const useBlocker = (blockerId: string, config: BlockerConfig, isActive = true): void => {\n  const { addBlocker, removeBlocker } = useUIBlockingStore();\n\n  useEffect(() => {\n    if (!isActive || !blockerId) {\n      return;\n    }\n\n    addBlocker(blockerId, config);\n\n    return () => {\n      removeBlocker(blockerId);\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [blockerId, isActive, addBlocker, removeBlocker]);\n};\n","import { useUIBlockingStore } from \"../store\";\n\n/**\n * Hook to check if a scope is currently blocked\n *\n * Returns a boolean indicating whether the specified scope(s) are blocked.\n * Automatically re-renders when the blocking state changes.\n *\n * @param scope - Scope or array of scopes to check (default: \"global\")\n * @returns True if any of the specified scopes are blocked\n *\n */\nexport const useIsBlocked = (scope?: string | ReadonlyArray<string>): boolean => {\n  return useUIBlockingStore((state) => state.isBlocked(scope));\n};\n","import { useCallback } from \"react\";\nimport { useUIBlockingStore } from \"../store\";\nimport { ASYNC_ACTION_PRIORITY } from \"../store\";\n\n/**\n * Hook to wrap async functions with automatic blocking/unblocking\n *\n * Creates a wrapper function that automatically adds a blocker before executing\n * the async function and removes it after completion (success or failure).\n *\n * @template T - The return type of the async function\n * @param actionId - Unique identifier for the action (used in blocker ID and reason)\n * @param scope - Scope(s) to block during execution (default: \"global\")\n * @returns Function that wraps async functions with blocking behavior\n *\n */\nexport const useAsyncAction = <T = unknown>(\n  actionId: string,\n  scope?: string | ReadonlyArray<string>\n): ((asyncFn: () => Promise<T>) => Promise<T>) => {\n  const { addBlocker, removeBlocker } = useUIBlockingStore();\n\n  const executeWithBlocking = useCallback(\n    async (asyncFn: () => Promise<T>): Promise<T> => {\n      const blockerId = `${actionId}-${Date.now().toString()}`;\n\n      try {\n        addBlocker(blockerId, {\n          scope,\n          reason: `Executing ${actionId}`,\n          priority: ASYNC_ACTION_PRIORITY,\n        });\n\n        return await asyncFn();\n      } finally {\n        removeBlocker(blockerId);\n      }\n    },\n    [actionId, scope, addBlocker, removeBlocker]\n  );\n\n  return executeWithBlocking;\n};\n"]}

package/dist/index.d.cts

@@ -0,0 +1,118 @@
+import * as zustand from 'zustand';
+
+/**
+ * Configuration for a blocker
+ */
+interface BlockerConfig {
+    scope?: string | ReadonlyArray<string>;
+    reason?: string;
+    priority?: number;
+    timestamp?: number;
+}
+/**
+ * Stored blocker with all required fields
+ */
+interface StoredBlocker {
+    scope: string | ReadonlyArray<string>;
+    reason: string;
+    priority: number;
+    timestamp: number;
+}
+/**
+ * Blocker information including its ID
+ */
+interface BlockerInfo extends StoredBlocker {
+    id: string;
+}
+/**
+ * Internal store state
+ */
+interface UIBlockingStoreState {
+    activeBlockers: Map<string, StoredBlocker>;
+}
+/**
+ * Store actions
+ */
+interface UIBlockingStoreActions {
+    addBlocker: (id: string, config?: BlockerConfig) => void;
+    removeBlocker: (id: string) => void;
+    isBlocked: (scope?: string | ReadonlyArray<string>) => boolean;
+    getBlockingInfo: (scope: string) => ReadonlyArray<BlockerInfo>;
+    clearAllBlockers: () => void;
+    clearBlockersForScope: (scope: string) => void;
+}
+/**
+ * Complete store type (state + actions)
+ */
+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
+ *
+ */
+declare const useUIBlockingStore: zustand.UseBoundStore<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;
+    };
+}>;
+
+/**
+ * Hook to automatically add and remove a blocker based on component lifecycle
+ *
+ * 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 the blocker
+ * @param config - Blocker configuration (scope, reason, priority)
+ * @param isActive - Whether the blocker is currently active (default: true)
+ *
+ */
+declare const useBlocker: (blockerId: string, config: BlockerConfig, isActive?: boolean) => void;
+
+/**
+ * Hook to check if a scope is currently blocked
+ *
+ * Returns a boolean indicating whether the specified scope(s) are blocked.
+ * Automatically re-renders when the blocking state changes.
+ *
+ * @param scope - Scope or array of scopes to check (default: "global")
+ * @returns True if any of the specified scopes are blocked
+ *
+ */
+declare const useIsBlocked: (scope?: string | ReadonlyArray<string>) => boolean;
+
+/**
+ * Hook to wrap async functions with automatic blocking/unblocking
+ *
+ * Creates a wrapper function that automatically adds a blocker before executing
+ * the async function and removes it after completion (success or failure).
+ *
+ * @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")
+ * @returns Function that wraps async functions with blocking behavior
+ *
+ */
+declare const useAsyncAction: <T = unknown>(actionId: string, scope?: string | ReadonlyArray<string>) => ((asyncFn: () => Promise<T>) => Promise<T>);
+
+export { type BlockerConfig, type BlockerInfo, type StoredBlocker, type UIBlockingStore, type UIBlockingStoreActions, type UIBlockingStoreState, useAsyncAction, useBlocker, useIsBlocked, useUIBlockingStore };

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+import * as zustand from 'zustand';
+
+/**
+ * Configuration for a blocker
+ */
+interface BlockerConfig {
+    scope?: string | ReadonlyArray<string>;
+    reason?: string;
+    priority?: number;
+    timestamp?: number;
+}
+/**
+ * Stored blocker with all required fields
+ */
+interface StoredBlocker {
+    scope: string | ReadonlyArray<string>;
+    reason: string;
+    priority: number;
+    timestamp: number;
+}
+/**
+ * Blocker information including its ID
+ */
+interface BlockerInfo extends StoredBlocker {
+    id: string;
+}
+/**
+ * Internal store state
+ */
+interface UIBlockingStoreState {
+    activeBlockers: Map<string, StoredBlocker>;
+}
+/**
+ * Store actions
+ */
+interface UIBlockingStoreActions {
+    addBlocker: (id: string, config?: BlockerConfig) => void;
+    removeBlocker: (id: string) => void;
+    isBlocked: (scope?: string | ReadonlyArray<string>) => boolean;
+    getBlockingInfo: (scope: string) => ReadonlyArray<BlockerInfo>;
+    clearAllBlockers: () => void;
+    clearBlockersForScope: (scope: string) => void;
+}
+/**
+ * Complete store type (state + actions)
+ */
+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
+ *
+ */
+declare const useUIBlockingStore: zustand.UseBoundStore<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;
+    };
+}>;
+
+/**
+ * Hook to automatically add and remove a blocker based on component lifecycle
+ *
+ * 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 the blocker
+ * @param config - Blocker configuration (scope, reason, priority)
+ * @param isActive - Whether the blocker is currently active (default: true)
+ *
+ */
+declare const useBlocker: (blockerId: string, config: BlockerConfig, isActive?: boolean) => void;
+
+/**
+ * Hook to check if a scope is currently blocked
+ *
+ * Returns a boolean indicating whether the specified scope(s) are blocked.
+ * Automatically re-renders when the blocking state changes.
+ *
+ * @param scope - Scope or array of scopes to check (default: "global")
+ * @returns True if any of the specified scopes are blocked
+ *
+ */
+declare const useIsBlocked: (scope?: string | ReadonlyArray<string>) => boolean;
+
+/**
+ * Hook to wrap async functions with automatic blocking/unblocking
+ *
+ * Creates a wrapper function that automatically adds a blocker before executing
+ * the async function and removes it after completion (success or failure).
+ *
+ * @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")
+ * @returns Function that wraps async functions with blocking behavior
+ *
+ */
+declare const useAsyncAction: <T = unknown>(actionId: string, scope?: string | ReadonlyArray<string>) => ((asyncFn: () => Promise<T>) => Promise<T>);
+
+export { type BlockerConfig, type BlockerInfo, type StoredBlocker, type UIBlockingStore, type UIBlockingStoreActions, type UIBlockingStoreState, useAsyncAction, useBlocker, useIsBlocked, useUIBlockingStore };

package/dist/index.js

@@ -0,0 +1,177 @@
+import { useEffect, useCallback } from 'react';
+import { create } from 'zustand';
+import { devtools } from 'zustand/middleware';
+
+// src/hooks/useBlocker.ts
+
+// src/store/uiBlockingStore.constants.ts
+var DEFAULT_SCOPE = "global";
+var DEFAULT_REASON = "Unknown";
+var DEFAULT_PRIORITY = 0;
+var ASYNC_ACTION_PRIORITY = 20;
+var DEVTOOLS_NAME = "UIBlocking";
+
+// src/store/uiBlockingStore.utils.ts
+function normalizeScopeToArray(scope) {
+  if (typeof scope === "string") {
+    return [scope];
+  }
+  return Array.from(scope);
+}
+
+// src/store/uiBlockingStore.actions.ts
+var createUIBlockingActions = (set, get) => ({
+  // State
+  activeBlockers: /* @__PURE__ */ new Map(),
+  // Actions
+  /**
+   * Add a blocker to the store
+   *
+   * @param id - Unique blocker identifier
+   * @param config - Optional blocker configuration
+   *
+   */
+  addBlocker: (id, config = {}) => {
+    set((state) => {
+      const newBlockers = new Map(state.activeBlockers);
+      const storedBlocker = {
+        scope: config.scope ?? DEFAULT_SCOPE,
+        reason: config.reason ?? DEFAULT_REASON,
+        priority: config.priority ?? DEFAULT_PRIORITY,
+        timestamp: config.timestamp ?? Date.now()
+      };
+      newBlockers.set(id, storedBlocker);
+      return { activeBlockers: newBlockers };
+    });
+  },
+  /**
+   * Remove a blocker from the store
+   *
+   * @param id - Blocker identifier to remove
+   *
+   */
+  removeBlocker: (id) => {
+    set((state) => {
+      const newBlockers = new Map(state.activeBlockers);
+      newBlockers.delete(id);
+      return { activeBlockers: newBlockers };
+    });
+  },
+  /**
+   * 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
+   *
+   */
+  isBlocked: (scope = DEFAULT_SCOPE) => {
+    const { activeBlockers } = get();
+    const scopes = normalizeScopeToArray(scope);
+    for (const [, blocker] of activeBlockers) {
+      if (blocker.scope === DEFAULT_SCOPE) {
+        return true;
+      }
+      const blockerScopes = normalizeScopeToArray(blocker.scope);
+      if (scopes.some((s) => blockerScopes.includes(s))) {
+        return true;
+      }
+    }
+    return false;
+  },
+  /**
+   * Get detailed blocking information for a specific scope
+   *
+   * @param scope - Scope to get blocking information for
+   * @returns Array of blockers affecting the scope, sorted by priority (highest first)
+   *
+   */
+  getBlockingInfo: (scope) => {
+    const { activeBlockers } = get();
+    const blockers = [];
+    for (const [id, blocker] of activeBlockers) {
+      const blockerScopes = normalizeScopeToArray(blocker.scope);
+      if (blocker.scope === DEFAULT_SCOPE || blockerScopes.includes(scope)) {
+        blockers.push({ id, ...blocker });
+      }
+    }
+    return blockers.sort((a, b) => b.priority - a.priority);
+  },
+  /**
+   * Clear all blockers from the store
+   */
+  clearAllBlockers: () => {
+    set({ activeBlockers: /* @__PURE__ */ new Map() });
+  },
+  /**
+   * Clear all blockers for a specific scope
+   *
+   * @param scope - Scope to clear blockers for
+   *
+   */
+  clearBlockersForScope: (scope) => {
+    set((state) => {
+      const newBlockers = /* @__PURE__ */ new Map();
+      for (const [id, blocker] of state.activeBlockers) {
+        const blockerScopes = normalizeScopeToArray(blocker.scope);
+        if (!blockerScopes.includes(scope)) {
+          newBlockers.set(id, blocker);
+        }
+      }
+      return { activeBlockers: newBlockers };
+    });
+  }
+});
+
+// src/store/uiBlockingStore.config.ts
+var devtoolsConfig = {
+  name: DEVTOOLS_NAME,
+  enabled: process.env.NODE_ENV !== "production"
+};
+
+// src/store/uiBlockingStore.store.ts
+var useUIBlockingStore = create()(
+  devtools(createUIBlockingActions, devtoolsConfig)
+);
+
+// src/hooks/useBlocker.ts
+var useBlocker = (blockerId, config, isActive = true) => {
+  const { addBlocker, removeBlocker } = useUIBlockingStore();
+  useEffect(() => {
+    if (!isActive || !blockerId) {
+      return;
+    }
+    addBlocker(blockerId, config);
+    return () => {
+      removeBlocker(blockerId);
+    };
+  }, [blockerId, isActive, addBlocker, removeBlocker]);
+};
+
+// src/hooks/useIsBlocked.ts
+var useIsBlocked = (scope) => {
+  return useUIBlockingStore((state) => state.isBlocked(scope));
+};
+var useAsyncAction = (actionId, scope) => {
+  const { addBlocker, removeBlocker } = useUIBlockingStore();
+  const executeWithBlocking = useCallback(
+    async (asyncFn) => {
+      const blockerId = `${actionId}-${Date.now().toString()}`;
+      try {
+        addBlocker(blockerId, {
+          scope,
+          reason: `Executing ${actionId}`,
+          priority: ASYNC_ACTION_PRIORITY
+        });
+        return await asyncFn();
+      } finally {
+        removeBlocker(blockerId);
+      }
+    },
+    [actionId, scope, addBlocker, removeBlocker]
+  );
+  return executeWithBlocking;
+};
+
+export { useAsyncAction, useBlocker, useIsBlocked, useUIBlockingStore };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/store/uiBlockingStore.constants.ts","../src/store/uiBlockingStore.utils.ts","../src/store/uiBlockingStore.actions.ts","../src/store/uiBlockingStore.config.ts","../src/store/uiBlockingStore.store.ts","../src/hooks/useBlocker.ts","../src/hooks/useIsBlocked.ts","../src/hooks/useAsyncAction.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Default values and constants for UI Blocking Store\n */\n\n/**\n * Default scope for blockers\n */\nexport const DEFAULT_SCOPE = \"global\" as const;\n\n/**\n * Default reason when none is provided\n */\nexport const DEFAULT_REASON = \"Unknown\" as const;\n\n/**\n * Default priority for blockers\n */\nexport const DEFAULT_PRIORITY = 0 as const;\n\n/**\n * Default priority for async actions\n */\nexport const ASYNC_ACTION_PRIORITY = 20 as const;\n\n/**\n * DevTools store name\n */\nexport const DEVTOOLS_NAME = \"UIBlocking\" as const;\n","/**\n * Normalize scope to array format\n *\n * @param scope - Single scope or array of scopes\n * @returns Array of scopes\n *\n * @internal\n */\nexport function normalizeScopeToArray(scope: string | ReadonlyArray<string>): Array<string> {\n  if (typeof scope === \"string\") {\n    return [scope];\n  }\n  return Array.from(scope);\n}\n","import type { StateCreator } from \"zustand\";\nimport type {\n  BlockerConfig,\n  BlockerInfo,\n  StoredBlocker,\n  UIBlockingStore,\n} from \"./uiBlockingStore.types\";\nimport { DEFAULT_SCOPE, DEFAULT_REASON, DEFAULT_PRIORITY } from \"./uiBlockingStore.constants\";\nimport { normalizeScopeToArray } from \"./uiBlockingStore.utils\";\n\n/**\n * UI Blocking Store Slice\n *\n * Implements the state and actions for UI blocking management.\n * This slice follows the Zustand slice pattern for better code organization.\n */\nexport const createUIBlockingActions: StateCreator<UIBlockingStore, [], [], UIBlockingStore> = (\n  set,\n  get\n) => ({\n  // State\n  activeBlockers: new Map(),\n\n  // Actions\n  /**\n   * Add a blocker to the store\n   *\n   * @param id - Unique blocker identifier\n   * @param config - Optional blocker configuration\n   *\n   */\n  addBlocker: (id: string, config: BlockerConfig = {}): void => {\n    set((state) => {\n      const newBlockers = new Map(state.activeBlockers);\n      const storedBlocker: StoredBlocker = {\n        scope: config.scope ?? DEFAULT_SCOPE,\n        reason: config.reason ?? DEFAULT_REASON,\n        priority: config.priority ?? DEFAULT_PRIORITY,\n        timestamp: config.timestamp ?? Date.now(),\n      };\n      newBlockers.set(id, storedBlocker);\n\n      return { activeBlockers: newBlockers };\n    });\n  },\n\n  /**\n   * Remove a blocker from the store\n   *\n   * @param id - Blocker identifier to remove\n   *\n   */\n  removeBlocker: (id: string): void => {\n    set((state) => {\n      const newBlockers = new Map(state.activeBlockers);\n      newBlockers.delete(id);\n\n      return { activeBlockers: newBlockers };\n    });\n  },\n\n  /**\n   * Check if a scope is currently blocked\n   *\n   * @param scope - Scope or array of scopes to check (default: \"global\")\n   * @returns True if any of the scopes are blocked\n   *\n   */\n  isBlocked: (scope: string | ReadonlyArray<string> = DEFAULT_SCOPE): boolean => {\n    const { activeBlockers } = get();\n    const scopes = normalizeScopeToArray(scope);\n\n    for (const [, blocker] of activeBlockers) {\n      // Global blocking blocks everything\n      if (blocker.scope === DEFAULT_SCOPE) {\n        return true;\n      }\n\n      // Check scope intersection\n      const blockerScopes = normalizeScopeToArray(blocker.scope);\n\n      if (scopes.some((s) => blockerScopes.includes(s))) {\n        return true;\n      }\n    }\n\n    return false;\n  },\n\n  /**\n   * Get detailed blocking information for a specific scope\n   *\n   * @param scope - Scope to get blocking information for\n   * @returns Array of blockers affecting the scope, sorted by priority (highest first)\n   *\n   */\n  getBlockingInfo: (scope: string): ReadonlyArray<BlockerInfo> => {\n    const { activeBlockers } = get();\n    const blockers: Array<BlockerInfo> = [];\n\n    for (const [id, blocker] of activeBlockers) {\n      const blockerScopes = normalizeScopeToArray(blocker.scope);\n\n      if (blocker.scope === DEFAULT_SCOPE || blockerScopes.includes(scope)) {\n        blockers.push({ id, ...blocker });\n      }\n    }\n\n    return blockers.sort((a, b) => b.priority - a.priority);\n  },\n\n  /**\n   * Clear all blockers from the store\n   */\n  clearAllBlockers: (): void => {\n    set({ activeBlockers: new Map() });\n  },\n\n  /**\n   * Clear all blockers for a specific scope\n   *\n   * @param scope - Scope to clear blockers for\n   *\n   */\n  clearBlockersForScope: (scope: string): void => {\n    set((state) => {\n      const newBlockers = new Map();\n\n      for (const [id, blocker] of state.activeBlockers) {\n        const blockerScopes = normalizeScopeToArray(blocker.scope);\n\n        if (!blockerScopes.includes(scope)) {\n          newBlockers.set(id, blocker);\n        }\n      }\n\n      return { activeBlockers: newBlockers };\n    });\n  },\n});\n","import type { DevtoolsOptions } from \"zustand/middleware\";\nimport { DEVTOOLS_NAME } from \"./uiBlockingStore.constants\";\n\n/**\n * DevTools configuration for UI Blocking Store\n *\n * Enables Redux DevTools integration only in development mode\n * for better debugging experience without production overhead.\n */\nexport const devtoolsConfig: DevtoolsOptions = {\n  name: DEVTOOLS_NAME,\n  enabled: process.env.NODE_ENV !== \"production\",\n};\n","import { create } from \"zustand\";\nimport { devtools } from \"zustand/middleware\";\nimport { createUIBlockingActions } from \"./uiBlockingStore.actions\";\nimport { devtoolsConfig } from \"./uiBlockingStore.config\";\nimport type { UIBlockingStore } from \"./uiBlockingStore.types\";\n\n/**\n * UI Blocking Store\n *\n * Global Zustand store for managing UI blocking state across the application.\n *\n * Features:\n * - Priority-based blocking system\n * - Scope-based blocking (global, specific areas, or multiple scopes)\n * - Automatic cleanup on unmount (when using hooks)\n * - DevTools integration for debugging\n *\n */\nexport const useUIBlockingStore = create<UIBlockingStore>()(\n  devtools(createUIBlockingActions, devtoolsConfig)\n);\n","import { useEffect } from \"react\";\nimport { useUIBlockingStore } from \"../store\";\nimport type { BlockerConfig } from \"../store\";\n\n/**\n * Hook to automatically add and remove a blocker based on component lifecycle\n *\n * Automatically adds a blocker when the component mounts (or when activated)\n * and removes it when the component unmounts (or when deactivated).\n *\n * @param blockerId - Unique identifier for the blocker\n * @param config - Blocker configuration (scope, reason, priority)\n * @param isActive - Whether the blocker is currently active (default: true)\n *\n */\nexport const useBlocker = (blockerId: string, config: BlockerConfig, isActive = true): void => {\n  const { addBlocker, removeBlocker } = useUIBlockingStore();\n\n  useEffect(() => {\n    if (!isActive || !blockerId) {\n      return;\n    }\n\n    addBlocker(blockerId, config);\n\n    return () => {\n      removeBlocker(blockerId);\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [blockerId, isActive, addBlocker, removeBlocker]);\n};\n","import { useUIBlockingStore } from \"../store\";\n\n/**\n * Hook to check if a scope is currently blocked\n *\n * Returns a boolean indicating whether the specified scope(s) are blocked.\n * Automatically re-renders when the blocking state changes.\n *\n * @param scope - Scope or array of scopes to check (default: \"global\")\n * @returns True if any of the specified scopes are blocked\n *\n */\nexport const useIsBlocked = (scope?: string | ReadonlyArray<string>): boolean => {\n  return useUIBlockingStore((state) => state.isBlocked(scope));\n};\n","import { useCallback } from \"react\";\nimport { useUIBlockingStore } from \"../store\";\nimport { ASYNC_ACTION_PRIORITY } from \"../store\";\n\n/**\n * Hook to wrap async functions with automatic blocking/unblocking\n *\n * Creates a wrapper function that automatically adds a blocker before executing\n * the async function and removes it after completion (success or failure).\n *\n * @template T - The return type of the async function\n * @param actionId - Unique identifier for the action (used in blocker ID and reason)\n * @param scope - Scope(s) to block during execution (default: \"global\")\n * @returns Function that wraps async functions with blocking behavior\n *\n */\nexport const useAsyncAction = <T = unknown>(\n  actionId: string,\n  scope?: string | ReadonlyArray<string>\n): ((asyncFn: () => Promise<T>) => Promise<T>) => {\n  const { addBlocker, removeBlocker } = useUIBlockingStore();\n\n  const executeWithBlocking = useCallback(\n    async (asyncFn: () => Promise<T>): Promise<T> => {\n      const blockerId = `${actionId}-${Date.now().toString()}`;\n\n      try {\n        addBlocker(blockerId, {\n          scope,\n          reason: `Executing ${actionId}`,\n          priority: ASYNC_ACTION_PRIORITY,\n        });\n\n        return await asyncFn();\n      } finally {\n        removeBlocker(blockerId);\n      }\n    },\n    [actionId, scope, addBlocker, removeBlocker]\n  );\n\n  return executeWithBlocking;\n};\n"]}

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@okyrychenko-dev/react-action-guard",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Elegant UI blocking management for React applications with priorities, scopes, and automatic cleanup",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts,.tsx",
+    "lint:fix": "eslint src --ext .ts,.tsx --fix",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx}\"",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "react",
+    "ui-blocking",
+    "state-management",
+    "zustand",
+    "typescript",
+    "loading",
+    "async-operations"
+  ],
+  "author": "Oleksandr Kyrychenko <your@email.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/okyrychenko-dev/react-action-guard"
+  },
+  "bugs": {
+    "url": "https://github.com/okyrychenko-dev/react-action-guard/issues"
+  },
+  "homepage": "https://github.com/okyrychenko-dev/react-action-guard#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^17.0.0 || ^18.0.0",
+    "zustand": "^4.5.7"
+  },
+  "dependencies": {
+    "immer": "^10.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.5",
+    "@typescript-eslint/eslint-plugin": "^8.46.4",
+    "@typescript-eslint/parser": "^8.46.4",
+    "@vitest/ui": "^4.0.9",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "happy-dom": "^20.0.10",
+    "husky": "^9.1.7",
+    "jsdom": "^27.2.0",
+    "prettier": "^3.6.2",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.3.3",
+    "typescript-eslint": "^8.46.4",
+    "vitest": "^4.0.9",
+    "zustand": "^5.0.8"
+  }
+}