js.foresight-devtools/dist/index.d.ts

Visual debugging tools for ForesightJS - mouse trajectory prediction and element interaction visualization

import { ForesightManager, ForesightManagerSettings, ForesightElementData } from 'js.foresight';

type DebuggerSettings = {
    /**
     * Whether to show visual debugging information on the screen.
     * This includes overlays for elements, hit slop areas, the predicted mouse path and a debug control panel.
     * @default true
     */
    showDebugger: boolean;
    /**
     * Determines if the debugger control panel should be initialized in a minimized state.
     *
     * @link https://foresightjs.com/docs/getting_started/debug
     *
     * @default false
     */
    isControlPanelDefaultMinimized: boolean;
    /**
     * Determines if name tags should be displayed visually above each registered element.
     * This is a helpful visual aid for identifying which elements are being tracked.
     *
     * @link https://foresightjs.com/docs/getting_started/debug
     *
     * @default false
     */
    showNameTags: boolean;
    /**
     * Specifies the default sorting order for the list of registered elements in the debugger panel.
     * - `'visibility'`: Sorts elements by their viewport visibility (visible elements first),
     *   with a secondary documentOrder sort.
     * - `'documentOrder'`: Sorts elements based on their order of appearance in the
     *   document's structure (matching the HTML source).
     * - `'insertionOrder'`: Sorts by registration order.
     *
     *
     * @link https://foresightjs.com/docs/getting_started/debug
     *
     * @default 'visibility'
     *
     */
    sortElementList: SortElementList;
};
type SortElementList = "documentOrder" | "visibility" | "insertionOrder";
type ForesightDebuggerData = {
    settings: Readonly<DebuggerSettings>;
};
type DebuggerBooleanSettingKeys = {
    [K in keyof DebuggerSettings]: Required<DebuggerSettings>[K] extends boolean ? K : never;
}[keyof DebuggerSettings];

declare class ForesightDebugger {
    private static debuggerInstance;
    private callbackAnimations;
    private foresightManagerInstance;
    private shadowHost;
    private shadowRoot;
    private debugContainer;
    private controlPanel;
    private _debuggerSettings;
    private debugElementOverlays;
    private predictedMouseIndicator;
    private mouseTrajectoryLine;
    private scrollTrajectoryLine;
    private managerSubscriptionsController;
    private constructor();
    private animationPositionObserver;
    get getDebuggerData(): Readonly<ForesightDebuggerData>;
    static initialize(foresightManager: ForesightManager, props?: Partial<DebuggerSettings>): ForesightDebugger | null;
    static get instance(): ForesightDebugger;
    private _setupDOM;
    private handleAnimationPositionChange;
    private static get isInitiated();
    alterDebuggerSettings(props?: Partial<DebuggerSettings>): void;
    private subscribeToManagerEvents;
    private handleElementDataUpdated;
    /**
     * Removes all debug overlays and data associated with an element.
     *
     * This method cleans up the link overlay, expanded overlay, and name label
     * for the specified element, removes it from internal tracking maps, and
     * refreshes the control panel's element list to reflect the removal.
     *
     * @param element - The ForesightElement to remove from debugging visualization
     */
    private handleUnregisterElement;
    private handleCallbackFired;
    private handleRegisterElement;
    private handleMouseTrajectoryUpdate;
    private handleScrollTrajectoryUpdate;
    private handleSettingsChanged;
    private createElementOverlays;
    private createOrUpdateElementOverlay;
    private toggleNameTagVisibility;
    private removeElementOverlay;
    private showCallbackAnimation;
    cleanup(): void;
}

declare class DebuggerControlPanel {
    private foresightManagerInstance;
    private debuggerInstance;
    private static debuggerControlPanelInstance;
    private shadowRoot;
    private controlsContainer;
    private controlPanelStyleElement;
    private elementListItemsContainer;
    private elementCountSpan;
    private callbackCountSpan;
    private elementListItems;
    private trajectoryEnabledCheckbox;
    private tabEnabledCheckbox;
    private scrollEnabledCheckbox;
    private historySizeSlider;
    private historyValueSpan;
    private predictionTimeSlider;
    private predictionValueSpan;
    private tabOffsetSlider;
    private tabOffsetValueSpan;
    private scrollMarginSlider;
    private scrollMarginValueSpan;
    private showNameTagsCheckbox;
    private sortOptionsPopup;
    private sortButton;
    private containerMinimizeButton;
    private allSettingsSectionsContainer;
    private debuggerElementsSection;
    private isContainerMinimized;
    private isMouseSettingsMinimized;
    private isKeyboardSettingsMinimized;
    private isScrollSettingsMinimized;
    private isGeneralSettingsMinimized;
    private readonly SESSION_STORAGE_KEY;
    private copySettingsButton;
    private minimizedElementCount;
    private copyTimeoutId;
    private closeSortDropdownHandler;
    private constructor();
    /**
     * The initialize method now creates the instance if needed,
     * then calls the setup method to ensure the UI is ready.
     */
    static initialize(foresightManager: ForesightManager, debuggerInstance: ForesightDebugger, shadowRoot: ShadowRoot, debuggerSettings: DebuggerSettings): DebuggerControlPanel;
    /**
     * All DOM creation and event listener setup logic is moved here.
     * This method can be called to "revive" a cleaned-up instance.
     */
    private _setupDOMAndListeners;
    private static get isInitiated();
    private loadSectionStatesFromSessionStorage;
    private saveSectionStatesToSessionStorage;
    private queryDOMElements;
    private handleCopySettings;
    private createInputEventListener;
    private createChangeEventListener;
    private createSectionVisibilityToggleEventListener;
    private setupEventListeners;
    private toggleMinimizeSection;
    private originalSectionStates;
    private updateContainerVisibilityState;
    private updateSortOptionUI;
    updateControlsState(managerSettings: ForesightManagerSettings, debuggerSettings: DebuggerSettings): void;
    private refreshRegisteredElementCountDisplay;
    removeElementFromList(elementData: ForesightElementData): void;
    updateElementVisibilityStatus(elementData: ForesightElementData): void;
    private sortAndReorderElements;
    addElementToList(elementData: ForesightElementData, sort?: boolean): void;
    private updateListItemContent;
    /**
     * The cleanup method is updated to be more thorough, nullifying all
     * DOM-related properties to put the instance in a dormant state.
     */
    cleanup(): void;
    private createControlContainer;
    private getStyles;
}

export { DebuggerControlPanel, ForesightDebugger };
export type { DebuggerBooleanSettingKeys, DebuggerSettings, ForesightDebuggerData, SortElementList };