content-security-toolkit 1.0.0

package/dist/utils/securityOverlayManager.d.ts

@@ -0,0 +1,260 @@
+import type { MediatorAware, ProtectionMediator } from "../core/mediator/types";
+/**
+ * Options for the security overlay
+ */
+export interface OverlayOptions {
+    /**
+     * Title to display in the overlay
+     */
+    title?: string;
+    /**
+     * Main message to display
+     */
+    message?: string;
+    /**
+     * Secondary message to display
+     */
+    secondaryMessage?: string;
+    /**
+     * Text color for the overlay
+     */
+    textColor?: string;
+    /**
+     * Background color for the overlay
+     */
+    backgroundColor?: string;
+    /**
+     * Z-index for the overlay (default: 2147483647)
+     */
+    zIndex?: string;
+    /**
+     * Whether to show a close button
+     */
+    showCloseButton?: boolean;
+    /**
+     * Text for the close button
+     */
+    closeButtonText?: string;
+    /**
+     * Callback when close button is clicked
+     */
+    onCloseButtonClick?: () => void;
+    /**
+     * Duration in milliseconds to show the overlay (0 for indefinite)
+     */
+    duration?: number;
+    /**
+     * Additional custom styles for the overlay
+     */
+    customStyles?: Record<string, string>;
+    /**
+     * Additional custom styles for the text
+     */
+    textStyles?: Record<string, string>;
+    /**
+     * Font size (ScreenshotStrategy - refactor)
+     */
+    fontSize?: string;
+    /**
+     * Additional HTML content to display in the overlay
+     */
+    additionalContent?: string;
+    /**
+     * Whether to block events (create an event blocker)
+     */
+    blockEvents?: boolean;
+    /**
+     * Whether to automatically restore the overlay if it's removed from the DOM
+     * @default true
+     */
+    autoRestore?: boolean;
+}
+/**
+ * Utility class to manage security overlays
+ */
+export declare class SecurityOverlayManager implements MediatorAware {
+    readonly COMPONENT_NAME = "SecurityOverlayManager";
+    private mediator;
+    private debugMode;
+    private logger;
+    private domObserver;
+    private overlays;
+    private activeOverlayId;
+    private overlayQueue;
+    private onElementsRemovedCallbacks;
+    /**
+     * Create a new SecurityOverlayManager
+     * @param debugMode Enable debug mode for troubleshooting
+     */
+    constructor(debugMode?: boolean);
+    /**
+     * Set the mediator to communicate with the other components
+     * @param mediator The protection mediator
+     */
+    setMediator(mediator: ProtectionMediator): void;
+    /**
+     * Check if an overlay with the same owner and type already exists
+     * @param owner The owner to check
+     * @param overlayType The overlay type to check
+     * @returns True if a matching overlay exists
+     */
+    private hasOverlayByOwnerAndType;
+    /**
+     * Handle overlay shown event
+     * @param event The protection event
+     */
+    private handleOverlayShown;
+    /**
+     * Handle overlay removed event
+     * @param event The protection event
+     */
+    private handleOverlayRemoved;
+    /**
+     * Handle overlay restored event
+     * @param event The protection event
+     */
+    private handleOverlayRestored;
+    /**
+     * Register a new overlay
+     * @param owner The strategy or component that owns this overlay
+     * @param overlayType The type of overlay (e.g., "screenshot", "devtools")
+     * @param options Options for the overlay
+     * @param priority Priority for display order (higher displays on top)
+     * @returns The ID of the registered overlay
+     */
+    registerOverlay(owner: string, overlayType: string, options: OverlayOptions, priority?: number): string;
+    /**
+     * Add an overlay to the queue
+     * @param overlayId ID of the overlay to add to queue
+     */
+    private addToQueue;
+    /**
+     * Show a specific overlay by ID
+     * @param overlayId ID of the overlay to show
+     * @returns True if the overlay was shown successfully
+     */
+    private showOverlayById;
+    /**
+     * Hide a specific overlay by ID without removing it from storage
+     * @param overlayId ID of the overlay to hide
+     * @param processQueue Whether to process the queue after hiding
+     * @returns True if the overlay was hidden successfully
+     */
+    private hideOverlayById;
+    /**
+     * Create overlay and blocker elements
+     * @param overlay The stored overlay information
+     * @returns Object containing the created elements
+     */
+    private createOverlayElements;
+    /**
+     * Remove a specific overlay by ID
+     * @param overlayId ID of the overlay to remove
+     * @returns True if the overlay was removed successfully
+     */
+    removeOverlayById(overlayId: string): boolean;
+    /**
+     * Remove all overlays for a specific owner
+     * @param owner The owner to remove overlays for
+     * @returns The number of overlays removed
+     */
+    removeOverlaysByOwner(owner: string): number;
+    /**
+     * Check and restore overlays for a specific owner
+     * @param owner The owner to check overlays for
+     * @returns The number of overlays restored
+     */
+    checkAndRestoreOverlaysByOwner(owner: string): number;
+    /**
+     * Create an overlay element
+     * @param options Options for the overlay
+     * @param owner The owner of the overlay (for data attribute)
+     * @returns The created overlay element
+     */
+    private createOverlay;
+    /**
+     * Create an event blocker that prevents interaction with the page
+     * @returns The created event blocker element
+     */
+    private createEventBlocker;
+    /**
+     * Set up DOM observer to detect when overlay elements are removed
+     * @param overlay The overlay to observe
+     */
+    private setupObserver;
+    /**
+     * Remove global event listeners that were added to document and window
+     */
+    private removeGlobalEventListeners;
+    /**
+     * Notify all callbacks when elements are removed
+     * @param removedElements The elements that were removed
+     */
+    private notifyElementsRemovedCallbacks;
+    /**
+     * Add a callback to be called when overlay elements are removed
+     * @param callback Callback function
+     */
+    addElementsRemovedCallback(callback: (removedElements: HTMLElement[]) => void): void;
+    /**
+     * Remove a callback
+     * @param callback Callback function to remove
+     */
+    removeElementsRemovedCallback(callback: (removedElements: HTMLElement[]) => void): void;
+    /**
+     * Get all overlays for a specific owner
+     * @param owner The owner to get overlays for
+     * @returns Array of overlay IDs
+     */
+    getOverlaysByOwner(owner: string): string[];
+    /**
+     * Get all active overlays
+     * @returns Array of active overlay IDs
+     */
+    getActiveOverlays(): string[];
+    /**
+     * Check if an overlay exists
+     * @param overlayId The overlay ID
+     * @returns True if the overlay exists
+     */
+    hasOverlay(overlayId: string): boolean;
+    /**
+     * Get the currently active overlay ID
+     * @returns The active overlay ID or null if none is active
+     */
+    getActiveOverlayId(): string | null;
+    /**
+     * Get the overlay queue
+     * @returns Array of overlay IDs in the queue
+     */
+    getOverlayQueue(): string[];
+    /**
+     * Clear all overlays
+     * @returns The number of overlays removed
+     */
+    clearAllOverlays(): number;
+    /**
+     * Set debug mode
+     * @param enabled Whether debug mode should be enabled
+     */
+    setDebugMode(enabled: boolean): void;
+    /**
+     * Get debug information about registered overlays
+     * @returns Object with debug information
+     */
+    getDebugInfo(): {
+        totalOverlays: number;
+        overlaysByOwner: Record<string, number>;
+        overlaysByType: Record<string, number>;
+        activeOverlayId: string | null;
+        queueLength: number;
+        overlayDetails: Array<{
+            id: string;
+            owner: string;
+            type: string;
+            isVisible: boolean;
+            priority: number;
+            createdAt: number;
+        }>;
+    };
+}