@okyrychenko-dev/react-action-guard-devtools 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,160 @@
+import { ReactElement } from 'react';
+import { BlockingAction, UIBlockingStore, Middleware } from '@okyrychenko-dev/react-action-guard';
+import { StoreApi } from 'zustand';
+
+/**
+ * Extended event stored in devtools history
+ */
+interface DevtoolsEvent {
+    /** Unique event identifier */
+    id: string;
+    /** The action that occurred */
+    action: BlockingAction;
+    /** ID of the blocker */
+    blockerId: string;
+    /** Blocker configuration at time of event */
+    config?: {
+        scope?: string | ReadonlyArray<string>;
+        reason?: string;
+        priority?: number;
+    };
+    /** Unix timestamp of the event */
+    timestamp: number;
+    /** Previous state (available on remove/update) */
+    prevState?: {
+        scope?: string | ReadonlyArray<string>;
+        reason?: string;
+        priority?: number;
+    };
+    /** Duration in ms (calculated for remove events) */
+    duration?: number;
+    /** Source of the blocking action */
+    source?: string;
+}
+/**
+ * Filter configuration for the timeline
+ */
+interface DevtoolsFilter {
+    /** Filter by action types */
+    actions: Array<BlockingAction>;
+    /** Filter by scope */
+    scopes: Array<string>;
+    /** Search query for blocker IDs */
+    search: string;
+}
+/**
+ * Position of the devtools panel
+ */
+type DevtoolsPosition = "left" | "right";
+/**
+ * Devtools store state
+ */
+interface DevtoolsState {
+    /** Event history */
+    events: Array<DevtoolsEvent>;
+    /** Maximum number of events to keep */
+    maxEvents: number;
+    /** Whether the panel is open */
+    isOpen: boolean;
+    /** Whether the panel is minimized */
+    isMinimized: boolean;
+    /** Active tab in the panel */
+    activeTab: "timeline" | "blockers";
+    /** Current filter settings */
+    filter: DevtoolsFilter;
+    /** Selected event for detail view */
+    selectedEventId: string | null;
+    /** Whether devtools is paused (stops recording) */
+    isPaused: boolean;
+}
+/**
+ * Devtools store actions
+ */
+interface DevtoolsActions {
+    /** Add a new event to history */
+    addEvent: (event: Omit<DevtoolsEvent, "id">) => void;
+    /** Clear all events */
+    clearEvents: VoidFunction;
+    /** Toggle panel open/closed */
+    toggleOpen: VoidFunction;
+    /** Set panel open state */
+    setOpen: (open: boolean) => void;
+    /** Toggle minimized state */
+    toggleMinimized: VoidFunction;
+    /** Set active tab */
+    setActiveTab: (tab: DevtoolsState["activeTab"]) => void;
+    /** Update filter settings */
+    setFilter: (filter: Partial<DevtoolsFilter>) => void;
+    /** Reset filters to default */
+    resetFilter: VoidFunction;
+    /** Select an event for detail view */
+    selectEvent: (eventId: string | null) => void;
+    /** Toggle pause state */
+    togglePause: VoidFunction;
+    /** Set max events limit */
+    setMaxEvents: (max: number) => void;
+}
+/**
+ * Complete devtools store type
+ */
+type DevtoolsStore = DevtoolsState & DevtoolsActions;
+
+/**
+ * Store API type for UIBlockingProvider integration
+ */
+type UIBlockingStoreApi = StoreApi<UIBlockingStore>;
+/**
+ * Props for the main ActionGuardDevtools component
+ */
+interface ActionGuardDevtoolsProps {
+    /** Position of the toggle button and panel */
+    position?: DevtoolsPosition;
+    /** Whether the panel is open by default */
+    defaultOpen?: boolean;
+    /** Maximum number of events to store */
+    maxEvents?: number;
+    /** Whether to show in production (default: false) */
+    showInProduction?: boolean;
+    /**
+     * Custom store instance from UIBlockingProvider.
+     * Use this when you have multiple isolated stores via UIBlockingProvider.
+     * If not provided, the global store is used.
+     */
+    store?: UIBlockingStoreApi;
+}
+
+declare function ActionGuardDevtools(props: ActionGuardDevtoolsProps): ReactElement | null;
+
+/**
+ * Devtools Store
+ *
+ * Global Zustand store for managing devtools state across the application.
+ *
+ * Features:
+ * - Event history with circular buffer
+ * - Timeline filtering by action/scope/search
+ * - Pause/resume recording
+ * - Panel open/minimize states
+ * - Automatic shallow comparison for selectors
+ */
+declare const useDevtoolsStore: {
+    (): DevtoolsStore;
+    <T>(selector: (state: DevtoolsStore) => T): T;
+};
+
+/**
+ * Selector for filtered events
+ */
+declare function selectFilteredEvents(state: DevtoolsStore): Array<DevtoolsEvent>;
+/**
+ * Get unique scopes from all events (for filter dropdown)
+ */
+declare function selectUniqueScopes(state: DevtoolsStore): Array<string>;
+
+declare const DEVTOOLS_MIDDLEWARE_NAME = "action-guard-devtools";
+/**
+ * Creates the devtools middleware that records events
+ */
+declare function createDevtoolsMiddleware(): Middleware;
+
+export { ActionGuardDevtools, DEVTOOLS_MIDDLEWARE_NAME, type DevtoolsActions, type DevtoolsEvent, type DevtoolsFilter, type DevtoolsPosition, type DevtoolsState, type DevtoolsStore, createDevtoolsMiddleware, selectFilteredEvents, selectUniqueScopes, useDevtoolsStore };

package/dist/index.d.ts

@@ -0,0 +1,160 @@
+import { ReactElement } from 'react';
+import { BlockingAction, UIBlockingStore, Middleware } from '@okyrychenko-dev/react-action-guard';
+import { StoreApi } from 'zustand';
+
+/**
+ * Extended event stored in devtools history
+ */
+interface DevtoolsEvent {
+    /** Unique event identifier */
+    id: string;
+    /** The action that occurred */
+    action: BlockingAction;
+    /** ID of the blocker */
+    blockerId: string;
+    /** Blocker configuration at time of event */
+    config?: {
+        scope?: string | ReadonlyArray<string>;
+        reason?: string;
+        priority?: number;
+    };
+    /** Unix timestamp of the event */
+    timestamp: number;
+    /** Previous state (available on remove/update) */
+    prevState?: {
+        scope?: string | ReadonlyArray<string>;
+        reason?: string;
+        priority?: number;
+    };
+    /** Duration in ms (calculated for remove events) */
+    duration?: number;
+    /** Source of the blocking action */
+    source?: string;
+}
+/**
+ * Filter configuration for the timeline
+ */
+interface DevtoolsFilter {
+    /** Filter by action types */
+    actions: Array<BlockingAction>;
+    /** Filter by scope */
+    scopes: Array<string>;
+    /** Search query for blocker IDs */
+    search: string;
+}
+/**
+ * Position of the devtools panel
+ */
+type DevtoolsPosition = "left" | "right";
+/**
+ * Devtools store state
+ */
+interface DevtoolsState {
+    /** Event history */
+    events: Array<DevtoolsEvent>;
+    /** Maximum number of events to keep */
+    maxEvents: number;
+    /** Whether the panel is open */
+    isOpen: boolean;
+    /** Whether the panel is minimized */
+    isMinimized: boolean;
+    /** Active tab in the panel */
+    activeTab: "timeline" | "blockers";
+    /** Current filter settings */
+    filter: DevtoolsFilter;
+    /** Selected event for detail view */
+    selectedEventId: string | null;
+    /** Whether devtools is paused (stops recording) */
+    isPaused: boolean;
+}
+/**
+ * Devtools store actions
+ */
+interface DevtoolsActions {
+    /** Add a new event to history */
+    addEvent: (event: Omit<DevtoolsEvent, "id">) => void;
+    /** Clear all events */
+    clearEvents: VoidFunction;
+    /** Toggle panel open/closed */
+    toggleOpen: VoidFunction;
+    /** Set panel open state */
+    setOpen: (open: boolean) => void;
+    /** Toggle minimized state */
+    toggleMinimized: VoidFunction;
+    /** Set active tab */
+    setActiveTab: (tab: DevtoolsState["activeTab"]) => void;
+    /** Update filter settings */
+    setFilter: (filter: Partial<DevtoolsFilter>) => void;
+    /** Reset filters to default */
+    resetFilter: VoidFunction;
+    /** Select an event for detail view */
+    selectEvent: (eventId: string | null) => void;
+    /** Toggle pause state */
+    togglePause: VoidFunction;
+    /** Set max events limit */
+    setMaxEvents: (max: number) => void;
+}
+/**
+ * Complete devtools store type
+ */
+type DevtoolsStore = DevtoolsState & DevtoolsActions;
+
+/**
+ * Store API type for UIBlockingProvider integration
+ */
+type UIBlockingStoreApi = StoreApi<UIBlockingStore>;
+/**
+ * Props for the main ActionGuardDevtools component
+ */
+interface ActionGuardDevtoolsProps {
+    /** Position of the toggle button and panel */
+    position?: DevtoolsPosition;
+    /** Whether the panel is open by default */
+    defaultOpen?: boolean;
+    /** Maximum number of events to store */
+    maxEvents?: number;
+    /** Whether to show in production (default: false) */
+    showInProduction?: boolean;
+    /**
+     * Custom store instance from UIBlockingProvider.
+     * Use this when you have multiple isolated stores via UIBlockingProvider.
+     * If not provided, the global store is used.
+     */
+    store?: UIBlockingStoreApi;
+}
+
+declare function ActionGuardDevtools(props: ActionGuardDevtoolsProps): ReactElement | null;
+
+/**
+ * Devtools Store
+ *
+ * Global Zustand store for managing devtools state across the application.
+ *
+ * Features:
+ * - Event history with circular buffer
+ * - Timeline filtering by action/scope/search
+ * - Pause/resume recording
+ * - Panel open/minimize states
+ * - Automatic shallow comparison for selectors
+ */
+declare const useDevtoolsStore: {
+    (): DevtoolsStore;
+    <T>(selector: (state: DevtoolsStore) => T): T;
+};
+
+/**
+ * Selector for filtered events
+ */
+declare function selectFilteredEvents(state: DevtoolsStore): Array<DevtoolsEvent>;
+/**
+ * Get unique scopes from all events (for filter dropdown)
+ */
+declare function selectUniqueScopes(state: DevtoolsStore): Array<string>;
+
+declare const DEVTOOLS_MIDDLEWARE_NAME = "action-guard-devtools";
+/**
+ * Creates the devtools middleware that records events
+ */
+declare function createDevtoolsMiddleware(): Middleware;
+
+export { ActionGuardDevtools, DEVTOOLS_MIDDLEWARE_NAME, type DevtoolsActions, type DevtoolsEvent, type DevtoolsFilter, type DevtoolsPosition, type DevtoolsState, type DevtoolsStore, createDevtoolsMiddleware, selectFilteredEvents, selectUniqueScopes, useDevtoolsStore };