@okyrychenko-dev/react-action-guard 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,5 +1,43 @@
 import * as zustand from 'zustand';
 
+type BlockingAction = "add" | "remove" | "update" | "cancel" | "timeout";
+type MiddlewareBlockerConfig = BlockerConfig;
+interface MiddlewareContext {
+    action: BlockingAction;
+    blockerId: string;
+    config?: MiddlewareBlockerConfig;
+    timestamp: number;
+    prevState?: MiddlewareBlockerConfig;
+}
+type Middleware = (context: MiddlewareContext) => void | Promise<void>;
+
+declare const loggerMiddleware: Middleware;
+
+type AnalyticsEventData = Record<string, string | number | ReadonlyArray<string> | undefined>;
+type AnalyticsProvider = "ga" | "mixpanel" | "amplitude";
+interface GoogleAnalyticsConfig {
+    provider: "ga";
+}
+interface MixpanelConfig {
+    provider: "mixpanel";
+}
+interface AmplitudeConfig {
+    provider: "amplitude";
+}
+interface CustomAnalyticsConfig {
+    track: (event: string, data: AnalyticsEventData) => void;
+}
+type AnalyticsConfig = GoogleAnalyticsConfig | MixpanelConfig | AmplitudeConfig | CustomAnalyticsConfig;
+
+declare const createAnalyticsMiddleware: (config: AnalyticsConfig) => Middleware;
+
+interface PerformanceConfig {
+    slowBlockThreshold?: number;
+    onSlowBlock?: (blockerId: string, duration: number) => void;
+}
+
+declare const createPerformanceMiddleware: (config?: PerformanceConfig) => Middleware;
+
 /**
  * Configuration for a blocker
  */
@@ -29,6 +67,7 @@ interface BlockerInfo extends StoredBlocker {
  */
 interface UIBlockingStoreState {
     activeBlockers: Map<string, StoredBlocker>;
+    middlewares: Map<string, Middleware>;
 }
 /**
  * Store actions
@@ -38,8 +77,11 @@ interface UIBlockingStoreActions {
     removeBlocker: (id: string) => void;
     isBlocked: (scope?: string | ReadonlyArray<string>) => boolean;
     getBlockingInfo: (scope: string) => ReadonlyArray<BlockerInfo>;
-    clearAllBlockers: () => void;
+    clearAllBlockers: VoidFunction;
     clearBlockersForScope: (scope: string) => void;
+    registerMiddleware: (name: string, middleware: Middleware) => void;
+    unregisterMiddleware: (name: string) => void;
+    runMiddlewares: (context: MiddlewareContext) => Promise<void>;
 }
 /**
  * Complete store type (state + actions)
@@ -115,4 +157,122 @@ declare const useIsBlocked: (scope?: string | ReadonlyArray<string>) => boolean;
  */
 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 };
+/**
+ * Configuration for conditional blocker hook.
+ *
+ * Note: Unlike the base BlockerConfig, the scope property is required here
+ * because conditional blockers must have a defined scope to check against.
+ */
+interface ConditionalBlockerConfig<TState = unknown> extends Omit<BlockerConfig, "scope"> {
+    /** Required scope(s) to block. Unlike base BlockerConfig, this is mandatory for conditional blockers. */
+    scope: string | ReadonlyArray<string>;
+    /** Function that determines whether blocking should be active */
+    condition: (state?: TState) => boolean;
+    /** Interval in milliseconds to check the condition (default: 1000ms) */
+    checkInterval?: number;
+    /** Optional state to pass to the condition function */
+    state?: TState;
+}
+
+/**
+ * Hook for conditional blocking based on a condition function.
+ *
+ * Periodically checks a condition and blocks/unblocks based on the result.
+ * The condition is evaluated at the specified interval (default 1000ms).
+ *
+ * @param blockerId - Unique identifier for this blocker
+ * @param config - Configuration including condition function and check interval
+ *
+ */
+declare const useConditionalBlocker: <TState = unknown>(blockerId: string, config: ConditionalBlockerConfig<TState>) => void;
+
+/**
+ * Configuration for the confirmation dialog
+ */
+interface ConfirmDialogConfig {
+    title: string;
+    message: string;
+    confirmText: string;
+    cancelText: string;
+}
+/**
+ * Configuration for confirmable blocker hook.
+ *
+ * The reason property can be used to provide a different blocking reason
+ * than the confirmMessage. If not provided, confirmMessage will be used as the reason.
+ */
+interface ConfirmableBlockerConfig extends BlockerConfig {
+    /** Message to display in the confirmation dialog */
+    confirmMessage: string;
+    /** Title for the confirmation dialog (default: "Confirm Action") */
+    confirmTitle?: string;
+    /** Text for the confirm button (default: "Confirm") */
+    confirmButtonText?: string;
+    /** Text for the cancel button (default: "Cancel") */
+    cancelButtonText?: string;
+    /** Callback to execute when confirmed. Can be async. */
+    onConfirm: () => void | Promise<void>;
+    /** Optional callback to execute when cancelled */
+    onCancel?: VoidFunction;
+}
+/**
+ * Return type for useConfirmableBlocker hook
+ */
+interface UseConfirmableBlockerReturn {
+    execute: VoidFunction;
+    isDialogOpen: boolean;
+    isExecuting: boolean;
+    confirmConfig: ConfirmDialogConfig;
+    onConfirm: () => Promise<void>;
+    onCancel: VoidFunction;
+}
+
+/**
+ * Hook for creating a confirmable action with blocking UI
+ *
+ */
+declare const useConfirmableBlocker: (blockerId: string, config: ConfirmableBlockerConfig) => UseConfirmableBlockerReturn;
+
+/**
+ * Schedule configuration for time-based blocking.
+ *
+ * You can specify the blocking period in two ways:
+ * 1. start + duration: Block for a specific duration after start time
+ * 2. start + end: Block between start and end times
+ *
+ * Note: If both duration and end are provided, duration takes precedence.
+ */
+interface BlockingSchedule {
+    /** Start time as ISO string, Date object, or timestamp */
+    start: string | Date | number;
+    /** Optional end time as ISO string, Date object, or timestamp */
+    end?: string | Date | number;
+    /** Duration in milliseconds (takes precedence over end if both provided) */
+    duration?: number;
+}
+/**
+ * Configuration for scheduled blocker hook
+ */
+interface ScheduledBlockerConfig extends BlockerConfig {
+    /** Schedule defining when blocking should be active */
+    schedule: BlockingSchedule;
+    /** Optional callback to execute when the blocking schedule starts */
+    onScheduleStart?: VoidFunction;
+    /** Optional callback to execute when the blocking schedule ends */
+    onScheduleEnd?: VoidFunction;
+}
+
+/**
+ * Hook for scheduling UI blocking for a specific time period.
+ *
+ * Blocks UI during a scheduled maintenance window or time period.
+ * Supports start/end times as Date objects, ISO strings, or timestamps.
+ * If both duration and end are provided, duration takes precedence.
+ *
+ * @param blockerId - Unique identifier for this blocker
+ * @param config - Configuration including schedule and callbacks
+ *
+ */
+declare const useScheduledBlocker: (blockerId: string, config: ScheduledBlockerConfig) => void;
+
+export { type AmplitudeConfig, type AnalyticsConfig, type AnalyticsEventData, type AnalyticsProvider, type BlockerConfig, type BlockerInfo, type BlockingAction, type BlockingSchedule, type ConditionalBlockerConfig, type ConfirmDialogConfig, type ConfirmableBlockerConfig, type CustomAnalyticsConfig, type GoogleAnalyticsConfig, type Middleware, type MiddlewareContext, type MixpanelConfig, type PerformanceConfig, type ScheduledBlockerConfig, type StoredBlocker, type UIBlockingStore, type UIBlockingStoreActions, type UIBlockingStoreState, type UseConfirmableBlockerReturn, createAnalyticsMiddleware, createPerformanceMiddleware, loggerMiddleware, useAsyncAction, useBlocker, useConditionalBlocker, useConfirmableBlocker, useIsBlocked, useScheduledBlocker, useUIBlockingStore };

package/dist/index.d.ts

@@ -1,5 +1,43 @@
 import * as zustand from 'zustand';
 
+type BlockingAction = "add" | "remove" | "update" | "cancel" | "timeout";
+type MiddlewareBlockerConfig = BlockerConfig;
+interface MiddlewareContext {
+    action: BlockingAction;
+    blockerId: string;
+    config?: MiddlewareBlockerConfig;
+    timestamp: number;
+    prevState?: MiddlewareBlockerConfig;
+}
+type Middleware = (context: MiddlewareContext) => void | Promise<void>;
+
+declare const loggerMiddleware: Middleware;
+
+type AnalyticsEventData = Record<string, string | number | ReadonlyArray<string> | undefined>;
+type AnalyticsProvider = "ga" | "mixpanel" | "amplitude";
+interface GoogleAnalyticsConfig {
+    provider: "ga";
+}
+interface MixpanelConfig {
+    provider: "mixpanel";
+}
+interface AmplitudeConfig {
+    provider: "amplitude";
+}
+interface CustomAnalyticsConfig {
+    track: (event: string, data: AnalyticsEventData) => void;
+}
+type AnalyticsConfig = GoogleAnalyticsConfig | MixpanelConfig | AmplitudeConfig | CustomAnalyticsConfig;
+
+declare const createAnalyticsMiddleware: (config: AnalyticsConfig) => Middleware;
+
+interface PerformanceConfig {
+    slowBlockThreshold?: number;
+    onSlowBlock?: (blockerId: string, duration: number) => void;
+}
+
+declare const createPerformanceMiddleware: (config?: PerformanceConfig) => Middleware;
+
 /**
  * Configuration for a blocker
  */
@@ -29,6 +67,7 @@ interface BlockerInfo extends StoredBlocker {
  */
 interface UIBlockingStoreState {
     activeBlockers: Map<string, StoredBlocker>;
+    middlewares: Map<string, Middleware>;
 }
 /**
  * Store actions
@@ -38,8 +77,11 @@ interface UIBlockingStoreActions {
     removeBlocker: (id: string) => void;
     isBlocked: (scope?: string | ReadonlyArray<string>) => boolean;
     getBlockingInfo: (scope: string) => ReadonlyArray<BlockerInfo>;
-    clearAllBlockers: () => void;
+    clearAllBlockers: VoidFunction;
     clearBlockersForScope: (scope: string) => void;
+    registerMiddleware: (name: string, middleware: Middleware) => void;
+    unregisterMiddleware: (name: string) => void;
+    runMiddlewares: (context: MiddlewareContext) => Promise<void>;
 }
 /**
  * Complete store type (state + actions)
@@ -115,4 +157,122 @@ declare const useIsBlocked: (scope?: string | ReadonlyArray<string>) => boolean;
  */
 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 };
+/**
+ * Configuration for conditional blocker hook.
+ *
+ * Note: Unlike the base BlockerConfig, the scope property is required here
+ * because conditional blockers must have a defined scope to check against.
+ */
+interface ConditionalBlockerConfig<TState = unknown> extends Omit<BlockerConfig, "scope"> {
+    /** Required scope(s) to block. Unlike base BlockerConfig, this is mandatory for conditional blockers. */
+    scope: string | ReadonlyArray<string>;
+    /** Function that determines whether blocking should be active */
+    condition: (state?: TState) => boolean;
+    /** Interval in milliseconds to check the condition (default: 1000ms) */
+    checkInterval?: number;
+    /** Optional state to pass to the condition function */
+    state?: TState;
+}
+
+/**
+ * Hook for conditional blocking based on a condition function.
+ *
+ * Periodically checks a condition and blocks/unblocks based on the result.
+ * The condition is evaluated at the specified interval (default 1000ms).
+ *
+ * @param blockerId - Unique identifier for this blocker
+ * @param config - Configuration including condition function and check interval
+ *
+ */
+declare const useConditionalBlocker: <TState = unknown>(blockerId: string, config: ConditionalBlockerConfig<TState>) => void;
+
+/**
+ * Configuration for the confirmation dialog
+ */
+interface ConfirmDialogConfig {
+    title: string;
+    message: string;
+    confirmText: string;
+    cancelText: string;
+}
+/**
+ * Configuration for confirmable blocker hook.
+ *
+ * The reason property can be used to provide a different blocking reason
+ * than the confirmMessage. If not provided, confirmMessage will be used as the reason.
+ */
+interface ConfirmableBlockerConfig extends BlockerConfig {
+    /** Message to display in the confirmation dialog */
+    confirmMessage: string;
+    /** Title for the confirmation dialog (default: "Confirm Action") */
+    confirmTitle?: string;
+    /** Text for the confirm button (default: "Confirm") */
+    confirmButtonText?: string;
+    /** Text for the cancel button (default: "Cancel") */
+    cancelButtonText?: string;
+    /** Callback to execute when confirmed. Can be async. */
+    onConfirm: () => void | Promise<void>;
+    /** Optional callback to execute when cancelled */
+    onCancel?: VoidFunction;
+}
+/**
+ * Return type for useConfirmableBlocker hook
+ */
+interface UseConfirmableBlockerReturn {
+    execute: VoidFunction;
+    isDialogOpen: boolean;
+    isExecuting: boolean;
+    confirmConfig: ConfirmDialogConfig;
+    onConfirm: () => Promise<void>;
+    onCancel: VoidFunction;
+}
+
+/**
+ * Hook for creating a confirmable action with blocking UI
+ *
+ */
+declare const useConfirmableBlocker: (blockerId: string, config: ConfirmableBlockerConfig) => UseConfirmableBlockerReturn;
+
+/**
+ * Schedule configuration for time-based blocking.
+ *
+ * You can specify the blocking period in two ways:
+ * 1. start + duration: Block for a specific duration after start time
+ * 2. start + end: Block between start and end times
+ *
+ * Note: If both duration and end are provided, duration takes precedence.
+ */
+interface BlockingSchedule {
+    /** Start time as ISO string, Date object, or timestamp */
+    start: string | Date | number;
+    /** Optional end time as ISO string, Date object, or timestamp */
+    end?: string | Date | number;
+    /** Duration in milliseconds (takes precedence over end if both provided) */
+    duration?: number;
+}
+/**
+ * Configuration for scheduled blocker hook
+ */
+interface ScheduledBlockerConfig extends BlockerConfig {
+    /** Schedule defining when blocking should be active */
+    schedule: BlockingSchedule;
+    /** Optional callback to execute when the blocking schedule starts */
+    onScheduleStart?: VoidFunction;
+    /** Optional callback to execute when the blocking schedule ends */
+    onScheduleEnd?: VoidFunction;
+}
+
+/**
+ * Hook for scheduling UI blocking for a specific time period.
+ *
+ * Blocks UI during a scheduled maintenance window or time period.
+ * Supports start/end times as Date objects, ISO strings, or timestamps.
+ * If both duration and end are provided, duration takes precedence.
+ *
+ * @param blockerId - Unique identifier for this blocker
+ * @param config - Configuration including schedule and callbacks
+ *
+ */
+declare const useScheduledBlocker: (blockerId: string, config: ScheduledBlockerConfig) => void;
+
+export { type AmplitudeConfig, type AnalyticsConfig, type AnalyticsEventData, type AnalyticsProvider, type BlockerConfig, type BlockerInfo, type BlockingAction, type BlockingSchedule, type ConditionalBlockerConfig, type ConfirmDialogConfig, type ConfirmableBlockerConfig, type CustomAnalyticsConfig, type GoogleAnalyticsConfig, type Middleware, type MiddlewareContext, type MixpanelConfig, type PerformanceConfig, type ScheduledBlockerConfig, type StoredBlocker, type UIBlockingStore, type UIBlockingStoreActions, type UIBlockingStoreState, type UseConfirmableBlockerReturn, createAnalyticsMiddleware, createPerformanceMiddleware, loggerMiddleware, useAsyncAction, useBlocker, useConditionalBlocker, useConfirmableBlocker, useIsBlocked, useScheduledBlocker, useUIBlockingStore };