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

package/README.md

@@ -36,8 +36,14 @@ 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
+
+## 1.0 Migration
+
+`1.0.0` removes public re-exports of internal `react-zustand-toolkit` helpers from the root package.
+
+If you previously imported `createShallowStore`, `createStoreToolkit`, `createStoreProvider`, or `createResolvedStoreHooks` from `@okyrychenko-dev/react-action-guard`, import them directly from `@okyrychenko-dev/react-zustand-toolkit` instead.
 
 ## Quick Start
 
@@ -65,7 +71,7 @@ npm run storybook
 
 ### Hooks
 
-#### `useBlocker(blockerId, config, isActive)`
+#### `useBlocker(blockerId, config, isActive?)`
 
 Automatically adds a blocker when the component mounts and removes it on unmount.
 
@@ -80,6 +86,8 @@ Automatically adds a blocker when the component mounts and removes it on unmount
   - `onTimeout?: (blockerId: string) => void` - Callback when auto-removed
 - `isActive?: boolean` - Whether the blocker is active (default: true)
 
+When `isActive` is `true`, changing `config` updates the existing blocker via `updateBlocker` without requiring unmount/remount.
+
 **Example:**
 
 ```jsx
@@ -422,9 +430,17 @@ function MicroFrontend() {
 
 #### Context Hooks
 
-- `useUIBlockingContext()` - Get store from context (throws if outside provider)
+- `useUIBlockingContext()` - Get store API from context (throws if outside provider)
+- `useOptionalUIBlockingContext()` - Get store API from context or `null` outside provider
 - `useIsInsideUIBlockingProvider()` - Check if inside a provider
 - `useUIBlockingStoreFromContext(selector)` - Select state from context store
+- `useResolvedStoreApi()` - Resolve to provider store API or global store API
+- `useResolvedValue(selector)` - Resolve to provider/global store and select with shallow comparison
+
+Legacy aliases remain available for backward compatibility:
+- `useOptionalContext()` -> `useOptionalUIBlockingContext()`
+- `useResolvedStore()` -> `useResolvedStoreApi()`
+- `useResolvedStoreWithSelector()` -> `useResolvedValue()`
 
 ### Store
 
@@ -505,15 +521,6 @@ uiBlockingStoreApi.getState().addBlocker("server-call", {
 });
 ```
 
-### Store Toolkit Helpers
-
-Advanced store helpers are re-exported from the internal toolkit for custom setups:
-
-- `createShallowStore`
-- `createStoreToolkit`
-- `createStoreProvider`
-- `createResolvedStoreHooks`
-
 ## Middleware System
 
 The library includes a powerful middleware system that allows you to hook into blocker lifecycle events for analytics, logging, and performance monitoring.
@@ -604,6 +611,9 @@ configureMiddleware([
 ```
 
 Note: `configureMiddleware` registers middleware on the global store. If you use `UIBlockingProvider`, register middleware via the provider's `middlewares` prop instead.
+Each `configureMiddleware(...)` call replaces previously configured global middlewares (`middleware-*`) and keeps provider-level middlewares untouched.
+
+Analytics middleware is SSR-safe: in non-browser environments it becomes a no-op for `ga`, `mixpanel`, and `amplitude` providers.
 
 ### Custom Middleware