@okyrychenko-dev/react-action-guard-devtools 0.1.2 → 0.2.0

package/dist/index.d.cts

@@ -124,10 +124,98 @@ interface ActionGuardDevtoolsProps {
 }
 
 /**
- * ActionGuardDevtools - Developer tools panel for UI blocking visualization.
+ * ActionGuardDevtools - Visual developer tools panel for debugging UI blocking.
  *
- * In production, returns null immediately without initializing any stores or event listeners.
- * Use `showInProduction` prop to override this behavior if needed.
+ * This component provides a floating developer tools panel that visualizes all UI blocking
+ * events in real-time. It shows active blockers, their priorities, scopes, and provides
+ * a timeline of all blocking events with filtering and search capabilities.
+ *
+ * **Key Features:**
+ * - Real-time visualization of active blockers
+ * - Timeline of all blocking events (add, remove, timeout)
+ * - Filter by action type, scope, or search term
+ * - Pause/resume event capture
+ * - Keyboard shortcuts (Esc to close, P to pause, C to clear)
+ * - Draggable and resizable panel
+ * - Works with both global store and custom store instances
+ *
+ * **Performance:**
+ * - Automatically disabled in production builds (returns `null`)
+ * - Only allocates resources in development
+ * - Uses `showInProduction` prop to override if needed
+ *
+ * **Integration:**
+ * - Automatically registers devtools middleware on mount
+ * - Cleans up middleware on unmount
+ * - No configuration required for basic usage
+ *
+ * @param props - Configuration props for the devtools panel
+ * @param props.position - Panel position: 'left' | 'right' | 'top' | 'bottom' (default: 'right')
+ * @param props.defaultOpen - Whether panel is open initially (default: false)
+ * @param props.maxEvents - Maximum events to store in timeline (default: 200)
+ * @param props.showInProduction - Show panel even in production (default: false)
+ * @param props.store - Custom store instance (default: global store)
+ *
+ * @returns React element in development, `null` in production (unless `showInProduction` is true)
+ *
+ * @example
+ * Basic usage (global store)
+ * ```tsx
+ * import { ActionGuardDevtools } from '@okyrychenko-dev/react-action-guard-devtools';
+ *
+ * function App() {
+ *   return (
+ *     <div>
+ *       <YourApp />
+ *       <ActionGuardDevtools />
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * With custom configuration
+ * ```tsx
+ * <ActionGuardDevtools
+ *   position="bottom"
+ *   defaultOpen={true}
+ *   maxEvents={500}
+ * />
+ * ```
+ *
+ * @example
+ * With custom store instance (isolated state)
+ * ```tsx
+ * import { UIBlockingProvider } from '@okyrychenko-dev/react-action-guard';
+ * import { ActionGuardDevtools } from '@okyrychenko-dev/react-action-guard-devtools';
+ *
+ * function IsolatedApp() {
+ *   return (
+ *     <UIBlockingProvider>
+ *       {({ store }) => (
+ *         <>
+ *           <YourApp />
+ *           <ActionGuardDevtools store={store} />
+ *         </>
+ *       )}
+ *     </UIBlockingProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Keyboard shortcuts
+ * ```
+ * Esc        - Close devtools panel
+ * Ctrl/⌘ + P - Toggle pause/resume event capture
+ * Ctrl/⌘ + K - Clear all events
+ * ```
+ *
+ * @see {@link https://github.com/okyrychenko-dev/react-action-guard-devtools | DevTools README}
+ * @see {@link createDevtoolsMiddleware} for manual middleware registration
+ *
+ * @public
+ * @since 0.6.0
  */
 declare function ActionGuardDevtools(props: ActionGuardDevtoolsProps): ReactElement | null;
 
@@ -159,7 +247,55 @@ declare function selectUniqueScopes(state: DevtoolsStore): Array<string>;
 
 declare const DEVTOOLS_MIDDLEWARE_NAME = "action-guard-devtools";
 /**
- * Creates the devtools middleware that records events
+ * Creates the devtools middleware that captures and records UI blocking events.
+ *
+ * This middleware intercepts all blocking events (add, remove, timeout, clear) and
+ * forwards them to the devtools store for visualization in the ActionGuardDevtools panel.
+ *
+ * The middleware calculates the duration of each blocker by tracking when it was added
+ * and when it was removed/timed out, providing insights into how long UI was blocked.
+ *
+ * **Note:** This middleware is automatically registered when you use the `ActionGuardDevtools`
+ * component. You typically don't need to call this function directly unless you're manually
+ * managing middleware registration.
+ *
+ * @returns Middleware function that can be registered with `configureMiddleware` or `registerMiddleware`
+ *
+ * @example
+ * Manual middleware registration (advanced usage)
+ * ```tsx
+ * import { uiBlockingStoreApi } from '@okyrychenko-dev/react-action-guard';
+ * import { createDevtoolsMiddleware, DEVTOOLS_MIDDLEWARE_NAME } from '@okyrychenko-dev/react-action-guard-devtools';
+ *
+ * // Register manually
+ * const middleware = createDevtoolsMiddleware();
+ * uiBlockingStoreApi.getState().registerMiddleware(DEVTOOLS_MIDDLEWARE_NAME, middleware);
+ *
+ * // Cleanup
+ * uiBlockingStoreApi.getState().unregisterMiddleware(DEVTOOLS_MIDDLEWARE_NAME);
+ * ```
+ *
+ * @example
+ * Automatic registration (recommended)
+ * ```tsx
+ * import { ActionGuardDevtools } from '@okyrychenko-dev/react-action-guard-devtools';
+ *
+ * // Middleware registered automatically when component mounts
+ * function App() {
+ *   return (
+ *     <>
+ *       <YourApp />
+ *       <ActionGuardDevtools />
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link ActionGuardDevtools} for automatic middleware registration
+ * @see {@link https://github.com/okyrychenko-dev/react-action-guard#middleware | Middleware documentation}
+ *
+ * @public
+ * @since 0.6.0
  */
 declare function createDevtoolsMiddleware(): Middleware;
 

package/dist/index.d.ts

@@ -124,10 +124,98 @@ interface ActionGuardDevtoolsProps {
 }
 
 /**
- * ActionGuardDevtools - Developer tools panel for UI blocking visualization.
+ * ActionGuardDevtools - Visual developer tools panel for debugging UI blocking.
  *
- * In production, returns null immediately without initializing any stores or event listeners.
- * Use `showInProduction` prop to override this behavior if needed.
+ * This component provides a floating developer tools panel that visualizes all UI blocking
+ * events in real-time. It shows active blockers, their priorities, scopes, and provides
+ * a timeline of all blocking events with filtering and search capabilities.
+ *
+ * **Key Features:**
+ * - Real-time visualization of active blockers
+ * - Timeline of all blocking events (add, remove, timeout)
+ * - Filter by action type, scope, or search term
+ * - Pause/resume event capture
+ * - Keyboard shortcuts (Esc to close, P to pause, C to clear)
+ * - Draggable and resizable panel
+ * - Works with both global store and custom store instances
+ *
+ * **Performance:**
+ * - Automatically disabled in production builds (returns `null`)
+ * - Only allocates resources in development
+ * - Uses `showInProduction` prop to override if needed
+ *
+ * **Integration:**
+ * - Automatically registers devtools middleware on mount
+ * - Cleans up middleware on unmount
+ * - No configuration required for basic usage
+ *
+ * @param props - Configuration props for the devtools panel
+ * @param props.position - Panel position: 'left' | 'right' | 'top' | 'bottom' (default: 'right')
+ * @param props.defaultOpen - Whether panel is open initially (default: false)
+ * @param props.maxEvents - Maximum events to store in timeline (default: 200)
+ * @param props.showInProduction - Show panel even in production (default: false)
+ * @param props.store - Custom store instance (default: global store)
+ *
+ * @returns React element in development, `null` in production (unless `showInProduction` is true)
+ *
+ * @example
+ * Basic usage (global store)
+ * ```tsx
+ * import { ActionGuardDevtools } from '@okyrychenko-dev/react-action-guard-devtools';
+ *
+ * function App() {
+ *   return (
+ *     <div>
+ *       <YourApp />
+ *       <ActionGuardDevtools />
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * With custom configuration
+ * ```tsx
+ * <ActionGuardDevtools
+ *   position="bottom"
+ *   defaultOpen={true}
+ *   maxEvents={500}
+ * />
+ * ```
+ *
+ * @example
+ * With custom store instance (isolated state)
+ * ```tsx
+ * import { UIBlockingProvider } from '@okyrychenko-dev/react-action-guard';
+ * import { ActionGuardDevtools } from '@okyrychenko-dev/react-action-guard-devtools';
+ *
+ * function IsolatedApp() {
+ *   return (
+ *     <UIBlockingProvider>
+ *       {({ store }) => (
+ *         <>
+ *           <YourApp />
+ *           <ActionGuardDevtools store={store} />
+ *         </>
+ *       )}
+ *     </UIBlockingProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Keyboard shortcuts
+ * ```
+ * Esc        - Close devtools panel
+ * Ctrl/⌘ + P - Toggle pause/resume event capture
+ * Ctrl/⌘ + K - Clear all events
+ * ```
+ *
+ * @see {@link https://github.com/okyrychenko-dev/react-action-guard-devtools | DevTools README}
+ * @see {@link createDevtoolsMiddleware} for manual middleware registration
+ *
+ * @public
+ * @since 0.6.0
  */
 declare function ActionGuardDevtools(props: ActionGuardDevtoolsProps): ReactElement | null;
 
@@ -159,7 +247,55 @@ declare function selectUniqueScopes(state: DevtoolsStore): Array<string>;
 
 declare const DEVTOOLS_MIDDLEWARE_NAME = "action-guard-devtools";
 /**
- * Creates the devtools middleware that records events
+ * Creates the devtools middleware that captures and records UI blocking events.
+ *
+ * This middleware intercepts all blocking events (add, remove, timeout, clear) and
+ * forwards them to the devtools store for visualization in the ActionGuardDevtools panel.
+ *
+ * The middleware calculates the duration of each blocker by tracking when it was added
+ * and when it was removed/timed out, providing insights into how long UI was blocked.
+ *
+ * **Note:** This middleware is automatically registered when you use the `ActionGuardDevtools`
+ * component. You typically don't need to call this function directly unless you're manually
+ * managing middleware registration.
+ *
+ * @returns Middleware function that can be registered with `configureMiddleware` or `registerMiddleware`
+ *
+ * @example
+ * Manual middleware registration (advanced usage)
+ * ```tsx
+ * import { uiBlockingStoreApi } from '@okyrychenko-dev/react-action-guard';
+ * import { createDevtoolsMiddleware, DEVTOOLS_MIDDLEWARE_NAME } from '@okyrychenko-dev/react-action-guard-devtools';
+ *
+ * // Register manually
+ * const middleware = createDevtoolsMiddleware();
+ * uiBlockingStoreApi.getState().registerMiddleware(DEVTOOLS_MIDDLEWARE_NAME, middleware);
+ *
+ * // Cleanup
+ * uiBlockingStoreApi.getState().unregisterMiddleware(DEVTOOLS_MIDDLEWARE_NAME);
+ * ```
+ *
+ * @example
+ * Automatic registration (recommended)
+ * ```tsx
+ * import { ActionGuardDevtools } from '@okyrychenko-dev/react-action-guard-devtools';
+ *
+ * // Middleware registered automatically when component mounts
+ * function App() {
+ *   return (
+ *     <>
+ *       <YourApp />
+ *       <ActionGuardDevtools />
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link ActionGuardDevtools} for automatic middleware registration
+ * @see {@link https://github.com/okyrychenko-dev/react-action-guard#middleware | Middleware documentation}
+ *
+ * @public
+ * @since 0.6.0
  */
 declare function createDevtoolsMiddleware(): Middleware;