js.foresight-devtools 0.0.2 → 1.0.0

package/README.md

@@ -32,13 +32,13 @@ yarn add -D js.foresight-devtools
 
 ```javascript
 import { ForesightManager } from "js.foresight"
-import { ForesightDebugger } from "js.foresight-devtools"
+import { ForesightDevtools } from "js.foresight-devtools"
 
 // Initialize ForesightJS
 ForesightManager.initialize()
 
 // Initialize development tools
-ForesightDebugger.initialize(ForesightManager.instance)
+ForesightDevtools.initialize()
 ```
 
 ## Configuration Options
@@ -49,6 +49,17 @@ type DevelopmentToolsSettings = {
   isControlPanelDefaultMinimized?: boolean
   showNameTags?: boolean // Show element names on overlays
   sortElementList?: "documentOrder" | "visibility" | "insertionOrder" // Control panel sorting
+  logging: {
+    logLocation: "controlPanel" | "console" | "both" | "none" // Where to log the Foresight Events
+    callbackCompleted: boolean
+    callbackInvoked: boolean
+    elementDataUpdated: boolean
+    elementRegistered: boolean
+    elementUnregistered: boolean
+    managerSettingsChanged: boolean
+    mouseTrajectoryUpdate: boolean
+    scrollTrajectoryUpdate: boolean
+  }
 }
 ```
 
@@ -63,11 +74,27 @@ type DevelopmentToolsSettings = {
 | `showNameTags`                   | `boolean`         | `true`       | Shows the element `name` (or `id` if no `name` is given) above registered elements                                                                                                |
 | `sortElementList`                | `SortElementList` | `visibility` | Controls element sorting in control panel: `visibility` sorts by viewport visibility, `documentOrder` sorts by HTML structure order, `insertionOrder` sorts by registration order |
 
+### Logging Configuration
+
+**TypeScript Type:** `LogEvents & { logLocation: LoggingLocations }`
+
+| Setting                  | Type                                                    | Default          | Description                                                                                    |
+| ------------------------ | ------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------- |
+| `logLocation`            | `"controlPanel"` \| `"console"` \| `"both"` \| `"none"` | `"controlPanel"` | Where to output the ForesightJS event logs                                                     |
+| `callbackCompleted`      | `boolean`                                               | `false`          | Log when element callbacks finish executing (includes success/error status and execution time) |
+| `callbackInvoked`        | `boolean`                                               | `false`          | Log when element callbacks are triggered (includes hit type: mouse/keyboard/scroll)            |
+| `elementDataUpdated`     | `boolean`                                               | `false`          | Log when element data changes (bounds updates, visibility changes)                             |
+| `elementRegistered`      | `boolean`                                               | `false`          | Log when new elements are registered with ForesightJS                                          |
+| `elementUnregistered`    | `boolean`                                               | `false`          | Log when elements are unregistered (includes reason: callbackHit/disconnected/apiCall)         |
+| `managerSettingsChanged` | `boolean`                                               | `false`          | Log when ForesightManager global settings are modified                                         |
+| `mouseTrajectoryUpdate`  | `boolean`                                               | `false`          | Log real-time mouse trajectory predictions (high frequency - use with caution)                 |
+| `scrollTrajectoryUpdate` | `boolean`                                               | `false`          | Log scroll direction predictions and trajectory updates                                        |
+
 ### Usage Example with All Options
 
 ```javascript
 import { ForesightManager } from "js.foresight"
-import { ForesightDebugger } from "js.foresight-devtools"
+import { ForesightDevtools } from "js.foresight-devtools"
 
 // Initialize ForesightJS
 ForesightManager.initialize({
@@ -79,11 +106,22 @@ ForesightManager.initialize({
 })
 
 // Initialize development tools with custom settings
-ForesightDebugger.initialize(ForesightManager.instance, {
+ForesightDevtools.initialize({
   showDebugger: true,
   isControlPanelDefaultMinimized: false,
   showNameTags: true,
   sortElementList: "visibility",
+  logging: {
+    logLocation: "controlPanel",
+    callbackCompleted: true,
+    callbackInvoked: true,
+    elementRegistered: true,
+    elementUnregistered: true,
+    elementDataUpdated: false, // High frequency - keep disabled for performance
+    managerSettingsChanged: true,
+    mouseTrajectoryUpdate: false, // High frequency - keep disabled for performance
+    scrollTrajectoryUpdate: false, // High frequency - keep disabled for performance
+  },
 })
 
 // Register elements as usual

package/dist/index.d.mts

@@ -0,0 +1,585 @@
+import * as lit from 'lit';
+import { LitElement, TemplateResult } from 'lit';
+import { ForesightEvent, ForesightElementData, ForesightManagerSettings as ForesightManagerSettings$2 } from 'js.foresight';
+import { ForesightEvent as ForesightEvent$1, HitSlop as HitSlop$1, UpdatedDataPropertyNames, CallbackHitType, Point, ScrollDirection, ForesightManagerSettings as ForesightManagerSettings$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 TabHeader extends LitElement {
+    static styles: lit.CSSResult[];
+    render(): lit.TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "tab-header": TabHeader;
+    }
+}
+
+declare class TabContent extends LitElement {
+    static styles: lit.CSSResult[];
+    noContentMessage: string;
+    hasContent: boolean;
+    render(): lit.TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "tab-content": TabContent;
+    }
+}
+
+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 ChipElement extends LitElement {
+    static styles: lit.CSSResult[];
+    title: string;
+    render(): lit.TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "chip-element": ChipElement;
+    }
+}
+
+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 SingleElement extends LitElement {
+    static styles: lit.CSSResult[];
+    elementData: ForesightElementData & {
+        elementId: string;
+    };
+    isActive: boolean;
+    isExpanded: boolean;
+    onToggle: ((elementId: string) => void) | undefined;
+    private getBorderColor;
+    private getStatusIndicatorClass;
+    private formatElementDetails;
+    render(): lit.TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "single-element": SingleElement;
+    }
+}
+
+declare class ElementTab extends LitElement {
+    static styles: lit.CSSResult;
+    private hitCount;
+    private visibleElementsCount;
+    private totalElementsCount;
+    private sortDropdown;
+    private sortOrder;
+    private elementListItems;
+    private noContentMessage;
+    private activeCallbacks;
+    private expandedElementIds;
+    private elementIdCounter;
+    private _abortController;
+    constructor();
+    private handleSortChange;
+    private generateElementId;
+    private handleElementToggle;
+    private updateVisibilityCounts;
+    private _generateHitsChipTitle;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private updateElementListFromManager;
+    private handleCallbackCompleted;
+    private getSortedElements;
+    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 Rect = {
+    top: number;
+    left: number;
+    right: number;
+    bottom: number;
+};
+type BaseForesightManagerSettings = {
+    /**
+     * Number of mouse positions to keep in history for trajectory calculation.
+     * A higher number might lead to smoother but slightly delayed predictions.
+     *
+     *
+     * @link https://foresightjs.com/docs/getting_started/config#available-global-settings
+     *
+     *
+     * **This value is clamped between 2 and 30.**
+     * @default 8
+     */
+    positionHistorySize: number;
+    /**
+     *
+     * @deprecated will be removed from v4.0
+     * ForesightJS now have its stand-alone devtools library with the debugger built-in
+     * @link https://github.com/spaansba/ForesightJS-DevTools
+     */
+    debug: boolean;
+    /**
+     * How far ahead (in milliseconds) to predict the mouse trajectory.
+     * A larger value means the prediction extends further into the future. (meaning it will trigger callbacks sooner)
+     *
+     * @link https://foresightjs.com/docs/getting_started/config#available-global-settings
+     *
+     * **This value is clamped between 10 and 200.**
+     * @default 120
+     */
+    trajectoryPredictionTime: number;
+    /**
+     * Whether to enable mouse trajectory prediction.
+     * If false, only direct hover/interaction is considered.
+     * @link https://foresightjs.com/docs/getting_started/config#available-global-settings
+     * @default true
+     */
+    enableMousePrediction: boolean;
+    /**
+     * Toggles whether keyboard prediction is on
+     *
+     * @link https://foresightjs.com/docs/getting_started/config#available-global-settings
+     * @default true
+     */
+    enableTabPrediction: boolean;
+    /**
+     * Sets the pixel distance to check from the mouse position in the scroll direction.
+     *
+     * @link https://foresightjs.com/docs/getting_started/config#available-global-settings
+     *
+     * **This value is clamped between 30 and 300.**
+     * @default 150
+     */
+    scrollMargin: number;
+    /**
+     * Toggles whether scroll prediction is on
+     * @link https://foresightjs.com/docs/getting_started/config#available-global-settings
+     * @default true
+     */
+    enableScrollPrediction: boolean;
+    /**
+     * Tab stops away from an element to trigger callback. Only works when @argument enableTabPrediction is true
+     *
+     * **This value is clamped between 0 and 20.**
+     * @default 2
+     */
+    tabOffset: number;
+};
+/**
+ * Configuration options for the ForesightManager
+ * @link https://foresightjs.com/docs/getting_started/config#available-global-settings
+ */
+type ForesightManagerSettings = BaseForesightManagerSettings & {
+    defaultHitSlop: Exclude<HitSlop, number>;
+};
+/**
+ * Fully invisible "slop" around the element.
+ * Basically increases the hover hitbox
+ */
+type HitSlop = Rect | number;
+type UpdatedManagerSetting = {
+    [K in keyof ForesightManagerSettings]: {
+        setting: K;
+        newValue: ForesightManagerSettings[K];
+        oldValue: ForesightManagerSettings[K];
+    };
+}[keyof ForesightManagerSettings];
+
+type SerializedEventType = ForesightEvent$1 | "serializationError";
+interface PayloadBase {
+    type: SerializedEventType;
+    localizedTimestamp: string;
+    summary: string;
+}
+interface ElementRegisteredPayload extends PayloadBase {
+    type: "elementRegistered";
+    name: string;
+    id: string;
+    registerCount: number;
+    hitslop: HitSlop$1;
+}
+interface ElementUnregisteredPayload extends PayloadBase {
+    type: "elementUnregistered";
+    name: string;
+    id: string;
+    registerCount: number;
+    unregisterReason: string;
+}
+interface ElementDataUpdatedPayload extends PayloadBase {
+    type: "elementDataUpdated";
+    name: string;
+    updatedProps: UpdatedDataPropertyNames[];
+    isIntersecting: boolean;
+}
+interface CallbackInvokedPayload extends PayloadBase {
+    type: "callbackInvoked";
+    name: string;
+    hitType: CallbackHitType;
+}
+interface CallbackCompletedBasePayload extends PayloadBase {
+    type: "callbackCompleted";
+    name: string;
+    callbackRunTimeFormatted: string;
+    callbackRunTimeRaw: number;
+    hitType: CallbackHitType;
+    status: "success" | "error";
+}
+type CallbackCompletedPayload = CallbackCompletedBasePayload & ({
+    status: "success";
+} | {
+    status: "error";
+    errorMessage: string;
+});
+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$1;
+    settingsChanged: UpdatedManagerSetting[];
+}
+interface SerializationErrorPayload extends PayloadBase {
+    type: "serializationError";
+    error: "Failed to serialize event data";
+    errorMessage: string;
+}
+type SerializedEventData = ElementRegisteredPayload | ElementUnregisteredPayload | ElementDataUpdatedPayload | CallbackInvokedPayload | CallbackCompletedPayload | MouseTrajectoryUpdatePayload | ScrollTrajectoryUpdatePayload | ManagerSettingsChangedPayload | SerializationErrorPayload;
+
+declare class SingleLog extends LitElement {
+    static styles: lit.CSSResult[];
+    private log;
+    isExpanded: boolean;
+    onToggle: ((logId: string) => void) | undefined;
+    constructor(log: SerializedEventData & {
+        logId: string;
+    });
+    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 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$2 | 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$2;
+    private displayValue;
+    private handleRangeInput;
+    private handleRangeChange;
+    willUpdate(changedProperties: Map<string, any>): 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 _abortController;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private _updateChangedSettings;
+    private _checkManagerSettingsChanges;
+    private _checkDevtoolsSettingsChanges;
+    private _handleDevtoolsSettingChange;
+    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[];
+    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>;
+    static initialize(props?: DeepPartial<DevtoolsSettings>): ForesightDevtools;
+    static get instance(): ForesightDevtools;
+    disconnectedCallback(): void;
+    private shouldUpdateSetting;
+    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 };