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

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

import * as lit from 'lit';
import { LitElement, TemplateResult, PropertyValues } from 'lit';
import { ForesightEvent, ForesightElementData, ForesightManagerSettings as ForesightManagerSettings$1 } from 'js.foresight';
import { ForesightEvent as ForesightEvent$1, ElementCallbackInfo, HitSlop, UpdatedDataPropertyNames, CallbackHitType, Point, ScrollDirection, ForesightManagerSettings, UpdatedManagerSetting, CallbackHits, ForesightElementData as ForesightElementData$1 } from 'js.foresight/types/types';

type DeepPartial<T> = T extends object ? {
    [P in keyof T]?: DeepPartial<T[P]>;
} : T;
type DevtoolsSettings = {
    /**
     * 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;
    logging: LogEvents & {
        logLocation: LoggingLocations;
    };
};
type LogEvents = {
    [K in ForesightEvent]: boolean;
};
type LoggingLocations = "controlPanel" | "console" | "both" | "none";
type SortElementList = "documentOrder" | "visibility" | "insertionOrder";
type DebuggerBooleanSettingKeys = {
    [K in keyof DevtoolsSettings]: Required<DevtoolsSettings>[K] extends boolean ? K : never;
}[keyof DevtoolsSettings];

declare class ChipElement extends LitElement {
    static styles: lit.CSSResult[];
    title: string;
    render(): lit.TemplateResult<1>;
}
declare global {
    interface HTMLElementTagNameMap {
        "chip-element": ChipElement;
    }
}

declare class TabContent extends LitElement {
    static styles: lit.CSSResult[];
    noContentMessage: string;
    hasContent: boolean;
    render(): lit.TemplateResult<1>;
}
declare global {
    interface HTMLElementTagNameMap {
        "tab-content": TabContent;
    }
}

declare class TabHeader extends LitElement {
    static styles: lit.CSSResult[];
    render(): lit.TemplateResult<1>;
}
declare global {
    interface HTMLElementTagNameMap {
        "tab-header": TabHeader;
    }
}

type DropdownOption = {
    value: string;
    label: string;
    title: string;
    icon: TemplateResult;
};
declare abstract class BaseDropdown extends LitElement {
    private static currentlyOpen;
    static styles: lit.CSSResult[];
    protected isDropdownOpen: boolean;
    dropdownOptions: DropdownOption[];
    connectedCallback(): void;
    disconnectedCallback(): void;
    protected _toggleDropdown: (event: MouseEvent) => void;
    protected _closeDropdown(): void;
    protected _positionDropdown(): void;
    protected _handleOutsideClick: (event: MouseEvent) => void;
    protected abstract _handleOptionClick(option: DropdownOption): void;
    protected abstract _getTriggerIcon(): TemplateResult;
    protected abstract _isOptionSelected(option: DropdownOption): boolean;
    protected abstract _getTriggerTitle(): string;
    protected abstract _getTriggerLabel(): string;
    render(): TemplateResult<1>;
}

declare class SingleSelectDropdown extends BaseDropdown {
    selectedOptionValue: string;
    onSelectionChange?: (value: string) => void;
    connectedCallback(): void;
    willUpdate(changedProperties: Map<PropertyKey, unknown>): void;
    protected _handleOptionClick(option: DropdownOption): void;
    protected _getTriggerIcon(): TemplateResult;
    protected _isOptionSelected(option: DropdownOption): boolean;
    protected _getTriggerTitle(): string;
    protected _getTriggerLabel(): string;
    private _getSelectedOption;
}
declare global {
    interface HTMLElementTagNameMap {
        "single-select-dropdown": SingleSelectDropdown;
    }
}

declare class CopyIcon extends LitElement {
    static styles: lit.CSSResult;
    title: string;
    onCopy?: (event: MouseEvent) => Promise<void> | void;
    private isCopied;
    private copyTimeout;
    private handleClick;
    disconnectedCallback(): void;
    render(): lit.TemplateResult<1>;
}
declare global {
    interface HTMLElementTagNameMap {
        "copy-icon": CopyIcon;
    }
}

declare class ExpandableItem extends LitElement {
    static styles: lit.CSSResult[];
    borderColor: string;
    showCopyButton: boolean;
    itemId: string;
    isExpanded: boolean;
    onToggle: ((itemId: string) => void) | undefined;
    private toggleExpand;
    private handleCopy;
    render(): lit.TemplateResult<1>;
}
declare global {
    interface HTMLElementTagNameMap {
        "expandable-item": ExpandableItem;
    }
}

declare class ReactivateCountdown extends LitElement {
    static styles: lit.CSSResult[];
    elementData: ForesightElementData;
    private remainingTime;
    private isCountdownActive;
    private intervalId;
    private startTime;
    connectedCallback(): void;
    disconnectedCallback(): void;
    updated(changedProperties: Map<string | number | symbol, unknown>): void;
    private checkAndStartCountdown;
    private startCountdown;
    private clearCountdown;
    private handleTimerClick;
    private formatTime;
    render(): lit.TemplateResult<1>;
}
declare global {
    interface HTMLElementTagNameMap {
        "reactivate-countdown": ReactivateCountdown;
    }
}

declare class SingleElement extends LitElement {
    static styles: lit.CSSResult[];
    elementData: ForesightElementData;
    isActive: boolean;
    isExpanded: boolean;
    onToggle: ((elementId: string) => void) | undefined;
    private currentDeviceStrategy;
    private _abortController;
    connectedCallback(): void;
    disconnectedCallback(): void;
    private getBorderColor;
    private getStatusIndicatorClass;
    private getStatusText;
    private formatElementDetails;
    private handleUnregister;
    render(): lit.TemplateResult<1>;
}
declare global {
    interface HTMLElementTagNameMap {
        "single-element": SingleElement;
    }
}

declare class ElementTab extends LitElement {
    static styles: lit.CSSResult;
    private hitCount;
    private sortDropdown;
    private sortOrder;
    private elementListItems;
    private noContentMessage;
    private runningCallbacks;
    private expandedElementIds;
    private _abortController;
    constructor();
    private handleSortChange;
    private handleElementToggle;
    private _generateHitsChipTitle;
    connectedCallback(): void;
    disconnectedCallback(): void;
    private updateElementListFromManager;
    private handleCallbackCompleted;
    private getSortedElements;
    private getActiveElements;
    private getInactiveElements;
    private sortByDocumentPosition;
    render(): lit.TemplateResult<1>;
}
declare global {
    interface HTMLElementTagNameMap {
        "element-tab": ElementTab;
    }
}

declare class MultiSelectDropdown extends BaseDropdown {
    static styles: lit.CSSResult[];
    selectedValues: string[];
    onSelectionChange?: (changedValue: string, isSelected: boolean) => void;
    protected _handleOptionClick(option: DropdownOption): void;
    protected _getTriggerIcon(): TemplateResult;
    protected _isOptionSelected(option: DropdownOption): boolean;
    protected _getTriggerTitle(): string;
    protected _getTriggerLabel(): string;
    render(): TemplateResult<1>;
}
declare global {
    interface HTMLElementTagNameMap {
        "multi-select-dropdown": MultiSelectDropdown;
    }
}

type SerializedEventType = ForesightEvent$1 | "serializationError" | "managerDataPayload";
interface PayloadBase {
    type: SerializedEventType;
    localizedTimestamp: string;
    summary: string;
    logId: string;
}
interface ElementRegisteredPayload extends PayloadBase {
    type: "elementRegistered";
    name: string;
    id: string;
    callbackInfo: ElementCallbackInfo;
    hitslop: HitSlop;
    meta: Record<string, unknown>;
}
interface ElementUnregisteredEvent extends PayloadBase {
    type: "elementUnregistered";
    name: string;
    id: string;
    callbackInfo: ElementCallbackInfo;
    meta: Record<string, unknown>;
    wasLastRegisteredElement: boolean;
}
interface ElementReactivatedPayload extends PayloadBase {
    type: "elementReactivated";
    name: string;
    id: string;
    callbackInfo: ElementCallbackInfo;
    meta: Record<string, unknown>;
}
interface ElementDataUpdatedPayload extends PayloadBase {
    type: "elementDataUpdated";
    name: string;
    updatedProps: UpdatedDataPropertyNames[];
    callbackInfo: ElementCallbackInfo;
    isIntersecting: boolean;
    meta: Record<string, unknown>;
}
interface CallbackInvokedPayload extends PayloadBase {
    type: "callbackInvoked";
    name: string;
    hitType: CallbackHitType;
    callbackInfo: ElementCallbackInfo;
    meta: Record<string, unknown>;
}
interface CallbackCompletedPayload extends PayloadBase {
    type: "callbackCompleted";
    elapsed: string;
    name: string;
    hitType: CallbackHitType;
    status: "success" | "error" | undefined;
    errorMessage: string | undefined | null;
    callbackInfo: ElementCallbackInfo;
    wasLastActiveElement: boolean;
    meta: Record<string, unknown>;
}
interface MouseTrajectoryUpdatePayload extends PayloadBase {
    type: "mouseTrajectoryUpdate";
    currentPoint: Point;
    predictedPoint: Point;
    positionCount: number;
    mousePredictionEnabled: boolean;
}
interface ScrollTrajectoryUpdatePayload extends PayloadBase {
    type: "scrollTrajectoryUpdate";
    currentPoint: Point;
    predictedPoint: Point;
    scrollDirection: ScrollDirection;
}
interface ManagerSettingsChangedPayload extends PayloadBase {
    type: "managerSettingsChanged";
    globalSettings: ForesightManagerSettings;
    settingsChanged: UpdatedManagerSetting[];
}
interface DeviceStrategyChangedPayload extends PayloadBase {
    type: "deviceStrategyChanged";
    oldStrategy: string;
    newStrategy: string;
}
interface SerializationErrorPayload extends PayloadBase {
    type: "serializationError";
    error: "Failed to serialize event data";
    errorMessage: string;
}
interface ManagerDataPayload extends PayloadBase {
    type: "managerDataPayload";
    warning: string;
    globalCallbackHits: CallbackHits;
    eventListenerCount: Record<string, number>;
    managerSettings: ForesightManagerSettings;
    registeredElements: Array<Omit<ForesightElementData$1, "element"> & {
        elementInfo: string;
    }>;
}
type SerializedEventData = ElementRegisteredPayload | ElementUnregisteredEvent | ElementReactivatedPayload | ElementDataUpdatedPayload | CallbackInvokedPayload | CallbackCompletedPayload | MouseTrajectoryUpdatePayload | ScrollTrajectoryUpdatePayload | ManagerSettingsChangedPayload | DeviceStrategyChangedPayload | ManagerDataPayload | SerializationErrorPayload;

declare class SingleLog extends LitElement {
    static styles: lit.CSSResult[];
    log: SerializedEventData;
    constructor(log: SerializedEventData);
    isExpanded: boolean;
    onToggle: ((logId: string) => void) | undefined;
    protected updated(changedProperties: PropertyValues<this>): void;
    private serializeLogDataWithoutSummary;
    private getLogTypeColor;
    private getEventDisplayName;
    private truncateLogSummary;
    render(): lit.TemplateResult<1>;
}
declare global {
    interface HTMLElementTagNameMap {
        "single-log": SingleLog;
    }
}

declare class LogTab extends LitElement {
    static styles: lit.CSSResult[];
    private logDropdown;
    private filterDropdown;
    private logLocation;
    private eventsEnabled;
    private logs;
    private expandedLogIds;
    private MAX_LOGS;
    private logIdCounter;
    noContentMessage: string;
    private _abortController;
    private _eventListeners;
    constructor();
    private handleLogLocationChange;
    private handleFilterChange;
    private getSelectedEventFilters;
    private shouldShowPerformanceWarning;
    private getNoLogsMessage;
    private handleLogToggle;
    private clearLogs;
    connectedCallback(): void;
    disconnectedCallback(): void;
    private setupDynamicEventListeners;
    private addForesightEventListener;
    private removeForesightEventListener;
    private removeAllEventListeners;
    private getEventColor;
    private handleEvent;
    private addLog;
    private logManagerData;
    private addManagerLog;
    private addEventLog;
    render(): lit.TemplateResult<1>;
}
declare global {
    interface HTMLElementTagNameMap {
        "log-tab": LogTab;
    }
}

declare class SettingItem extends LitElement {
    static styles: lit.CSSResult[];
    header: string;
    description: string;
    render(): lit.TemplateResult<1>;
}
declare global {
    interface HTMLElementTagNameMap {
        "setting-item": SettingItem;
    }
}

declare class SettingItemCheckbox extends LitElement {
    static styles: lit.CSSResult[];
    isChecked: boolean;
    header: string;
    description: string;
    setting: keyof ForesightManagerSettings$1 | keyof DevtoolsSettings;
    private handleCheckboxChange;
    render(): lit.TemplateResult<1>;
}
declare global {
    interface HTMLElementTagNameMap {
        "setting-item-checkbox": SettingItemCheckbox;
    }
}

declare class SettingItemRange extends LitElement {
    static styles: lit.CSSResult[];
    minValue: number;
    maxValue: number;
    currentValue: number;
    unit: string;
    header: string;
    description: string;
    setting: keyof ForesightManagerSettings$1;
    private displayValue;
    private handleRangeInput;
    private handleRangeChange;
    willUpdate(changedProperties: PropertyValues): void;
    render(): lit.TemplateResult<1>;
}
declare global {
    interface HTMLElementTagNameMap {
        "setting-item-range": SettingItemRange;
    }
}

declare class SettingsTab extends LitElement {
    static styles: lit.CSSResult;
    private managerSettings;
    private initialSettings;
    private devtoolsSettings;
    private changedSettings;
    private touchDeviceStrategyOptions;
    private _abortController;
    constructor();
    connectedCallback(): void;
    disconnectedCallback(): void;
    private _updateChangedSettings;
    private _checkManagerSettingsChanges;
    private _checkDevtoolsSettingsChanges;
    private _handleDevtoolsSettingChange;
    private _handleTouchDeviceStrategyChange;
    private handleCopySettings;
    private generateSettingsCode;
    render(): lit.TemplateResult<1>;
}
declare global {
    interface HTMLElementTagNameMap {
        "settings-tab": SettingsTab;
    }
}

declare class ElementOverlays extends LitElement {
    private overlayMap;
    private callbackAnimations;
    private containerElement;
    static styles: lit.CSSResult[];
    private _abortController;
    connectedCallback(): void;
    private createElementOverlays;
    private updateElementOverlays;
    private createOrUpdateElementOverlay;
    private removeElementOverlay;
    private clearCallbackAnimationTimeout;
    private highlightElementCallback;
    private unhighlightElementCallback;
    updateNameTagVisibility(showNameTags: boolean): void;
    disconnectedCallback(): void;
    render(): lit.TemplateResult<1>;
}
declare global {
    interface HTMLElementTagNameMap {
        "element-overlays": ElementOverlays;
    }
}

declare class DebugOverlay extends LitElement {
    static styles: lit.CSSResult[];
    private _abortController;
    private _strategy;
    connectedCallback(): void;
    private handleDeviceStrategyChange;
    disconnectedCallback(): void;
    render(): lit.TemplateResult<1>;
}
declare global {
    interface HTMLElementTagNameMap {
        "debug-overlay": DebugOverlay;
    }
}

declare class ForesightDevtools extends LitElement {
    static styles: lit.CSSResult[];
    private isInitialized;
    private static _instance;
    devtoolsSettings: Required<DevtoolsSettings>;
    private constructor();
    private static createAndAppendInstance;
    static initialize(props?: DeepPartial<DevtoolsSettings>): ForesightDevtools;
    static get instance(): ForesightDevtools;
    disconnectedCallback(): void;
    private shouldUpdateSetting;
    private updateLoggingSetting;
    alterDevtoolsSettings(props?: DeepPartial<DevtoolsSettings>): void;
    private cleanup;
    render(): lit.TemplateResult<1>;
}
declare global {
    interface HTMLElementTagNameMap {
        "foresight-devtools": ForesightDevtools;
    }
}

export { type DebuggerBooleanSettingKeys, type DevtoolsSettings, ForesightDevtools, type SortElementList };