js.foresight-devtools 1.0.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2025 Bart Spaans
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Bart Spaans
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
21
  SOFTWARE.
package/README.md CHANGED
@@ -1,169 +1,169 @@
1
- # ForesightJS Development Tools
2
-
3
- [![npm version](https://img.shields.io/npm/v/js.foresight-devtools.svg)](https://www.npmjs.com/package/js.foresight-devtools)
4
- [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
5
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
-
7
- Visual development tools for [ForesightJS](https://foresightjs.com/) - a library that predicts user intent by analyzing mouse movements, scroll behavior, and keyboard navigation to enable proactive actions like prefetching.
8
-
9
- ## What are the ForesightJS Development Tools?
10
-
11
- The ForesightJS Development Tools are a companion development package that provides visual development capabilities for ForesightJS implementations. They help developers understand and tune how ForesightJS is working in their applications by providing real-time visualization of:
12
-
13
- - **Mouse trajectory predictions** - See predicted cursor paths and intersection points
14
- - **Element bounds and hit slop areas** - Visualize registered elements and their interaction zones
15
- - **Keyboard navigation sequences** - Track tab-based navigation predictions
16
- - **Callback execution** - Monitor when and why prediction callbacks fire
17
- - **Real-time settings control** - Adjust ForesightJS parameters on the fly
18
-
19
- ![ForesightJS Development Tools Demo](https://github.com/user-attachments/assets/36c81a82-fee7-43d6-ba1e-c48214136f90)
20
-
21
- ## Installation
22
-
23
- ```bash
24
- pnpm add -D js.foresight-devtools
25
- # or
26
- npm install -D js.foresight-devtools
27
- # or
28
- yarn add -D js.foresight-devtools
29
- ```
30
-
31
- ## Basic Usage
32
-
33
- ```javascript
34
- import { ForesightManager } from "js.foresight"
35
- import { ForesightDevtools } from "js.foresight-devtools"
36
-
37
- // Initialize ForesightJS
38
- ForesightManager.initialize()
39
-
40
- // Initialize development tools
41
- ForesightDevtools.initialize()
42
- ```
43
-
44
- ## Configuration Options
45
-
46
- ```typescript
47
- type DevelopmentToolsSettings = {
48
- showDebugger?: boolean
49
- isControlPanelDefaultMinimized?: boolean
50
- showNameTags?: boolean // Show element names on overlays
51
- sortElementList?: "documentOrder" | "visibility" | "insertionOrder" // Control panel sorting
52
- logging: {
53
- logLocation: "controlPanel" | "console" | "both" | "none" // Where to log the Foresight Events
54
- callbackCompleted: boolean
55
- callbackInvoked: boolean
56
- elementDataUpdated: boolean
57
- elementRegistered: boolean
58
- elementUnregistered: boolean
59
- managerSettingsChanged: boolean
60
- mouseTrajectoryUpdate: boolean
61
- scrollTrajectoryUpdate: boolean
62
- }
63
- }
64
- ```
65
-
66
- ### Available Development Tools Settings
67
-
68
- **TypeScript Type:** `DevelopmentToolsSettings`
69
-
70
- | Setting | Type | Default | Description |
71
- | -------------------------------- | ----------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
72
- | `showDebugger` | `boolean` | `true` | Controls whether the development tools are visible and active |
73
- | `isControlPanelDefaultMinimized` | `boolean` | `false` | When true, the development tools control panel will be minimized on page load |
74
- | `showNameTags` | `boolean` | `true` | Shows the element `name` (or `id` if no `name` is given) above registered elements |
75
- | `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 |
76
-
77
- ### Logging Configuration
78
-
79
- **TypeScript Type:** `LogEvents & { logLocation: LoggingLocations }`
80
-
81
- | Setting | Type | Default | Description |
82
- | ------------------------ | ------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------- |
83
- | `logLocation` | `"controlPanel"` \| `"console"` \| `"both"` \| `"none"` | `"controlPanel"` | Where to output the ForesightJS event logs |
84
- | `callbackCompleted` | `boolean` | `false` | Log when element callbacks finish executing (includes success/error status and execution time) |
85
- | `callbackInvoked` | `boolean` | `false` | Log when element callbacks are triggered (includes hit type: mouse/keyboard/scroll) |
86
- | `elementDataUpdated` | `boolean` | `false` | Log when element data changes (bounds updates, visibility changes) |
87
- | `elementRegistered` | `boolean` | `false` | Log when new elements are registered with ForesightJS |
88
- | `elementUnregistered` | `boolean` | `false` | Log when elements are unregistered (includes reason: callbackHit/disconnected/apiCall) |
89
- | `managerSettingsChanged` | `boolean` | `false` | Log when ForesightManager global settings are modified |
90
- | `mouseTrajectoryUpdate` | `boolean` | `false` | Log real-time mouse trajectory predictions (high frequency - use with caution) |
91
- | `scrollTrajectoryUpdate` | `boolean` | `false` | Log scroll direction predictions and trajectory updates |
92
-
93
- ### Usage Example with All Options
94
-
95
- ```javascript
96
- import { ForesightManager } from "js.foresight"
97
- import { ForesightDevtools } from "js.foresight-devtools"
98
-
99
- // Initialize ForesightJS
100
- ForesightManager.initialize({
101
- trajectoryPredictionTime: 100,
102
- defaultHitSlop: { top: 10, right: 10, bottom: 10, left: 10 },
103
- enableMousePrediction: true,
104
- enableTabPrediction: true,
105
- enableScrollPrediction: true,
106
- })
107
-
108
- // Initialize development tools with custom settings
109
- ForesightDevtools.initialize({
110
- showDebugger: true,
111
- isControlPanelDefaultMinimized: false,
112
- showNameTags: true,
113
- sortElementList: "visibility",
114
- logging: {
115
- logLocation: "controlPanel",
116
- callbackCompleted: true,
117
- callbackInvoked: true,
118
- elementRegistered: true,
119
- elementUnregistered: true,
120
- elementDataUpdated: false, // High frequency - keep disabled for performance
121
- managerSettingsChanged: true,
122
- mouseTrajectoryUpdate: false, // High frequency - keep disabled for performance
123
- scrollTrajectoryUpdate: false, // High frequency - keep disabled for performance
124
- },
125
- })
126
-
127
- // Register elements as usual
128
- ForesightManager.instance.register({
129
- element: document.getElementById("my-button"),
130
- callback: () => {
131
- console.log("Prediction triggered!")
132
- },
133
- name: "my-button", // This name will appear in the development tools
134
- })
135
- ```
136
-
137
- ## Development Workflow
138
-
139
- The development tools are particularly useful when:
140
-
141
- 1. **Setting up ForesightJS** for the first time in an application
142
- 2. **Fine-tuning prediction parameters** for specific UI components
143
- 3. **Debugging callback execution** issues or unexpected behavior
144
- 4. **Optimizing hit slop areas** for better user experience
145
- 5. **Understanding prediction accuracy** across different interaction patterns
146
-
147
- ## Framework Integration
148
-
149
- Since both ForesightJS and the development tools are framework-agnostic, you can use them together in any JavaScript environment:
150
-
151
- - React / Next.js
152
- - Vue / Nuxt
153
- - Angular
154
- - Svelte / SvelteKit
155
- - Vanilla JavaScript
156
-
157
- ## Requirements
158
-
159
- - **js.foresight** ^3.0.0 (peer dependency)
160
-
161
- ## License
162
-
163
- MIT © [Bart Spaans](https://github.com/spaansba)
164
-
165
- ## Related
166
-
167
- - [ForesightJS](https://foresightjs.com/) - The main prediction library
168
- - [Documentation](https://foresightjs.com/docs) - Comprehensive guides and API reference
169
- - [GitHub](https://github.com/spaansba/ForesightJS) - Source code and issues
1
+ # ForesightJS Development Tools
2
+
3
+ [![npm version](https://img.shields.io/npm/v/js.foresight-devtools.svg)](https://www.npmjs.com/package/js.foresight-devtools)
4
+ [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
+
7
+ Visual development tools for [ForesightJS](https://foresightjs.com/) - a library that predicts user intent by analyzing mouse movements, scroll behavior, and keyboard navigation to enable proactive actions like prefetching.
8
+
9
+ ## What are the ForesightJS Development Tools?
10
+
11
+ The ForesightJS Development Tools are a companion development package that provides visual development capabilities for ForesightJS implementations. They help developers understand and tune how ForesightJS is working in their applications by providing real-time visualization of:
12
+
13
+ - **Mouse trajectory predictions** - See predicted cursor paths and intersection points
14
+ - **Element bounds and hit slop areas** - Visualize registered elements and their interaction zones
15
+ - **Keyboard navigation sequences** - Track tab-based navigation predictions
16
+ - **Callback execution** - Monitor when and why prediction callbacks fire
17
+ - **Real-time settings control** - Adjust ForesightJS parameters on the fly
18
+
19
+ ![ForesightJS Development Tools Demo](https://github.com/user-attachments/assets/36c81a82-fee7-43d6-ba1e-c48214136f90)
20
+
21
+ ## Installation
22
+
23
+ ```bash
24
+ pnpm add -D js.foresight-devtools
25
+ # or
26
+ npm install -D js.foresight-devtools
27
+ # or
28
+ yarn add -D js.foresight-devtools
29
+ ```
30
+
31
+ ## Basic Usage
32
+
33
+ ```javascript
34
+ import { ForesightManager } from "js.foresight"
35
+ import { ForesightDevtools } from "js.foresight-devtools"
36
+
37
+ // Initialize ForesightJS
38
+ ForesightManager.initialize()
39
+
40
+ // Initialize development tools
41
+ ForesightDevtools.initialize()
42
+ ```
43
+
44
+ ## Configuration Options
45
+
46
+ ```typescript
47
+ type DevelopmentToolsSettings = {
48
+ showDebugger?: boolean
49
+ isControlPanelDefaultMinimized?: boolean
50
+ showNameTags?: boolean // Show element names on overlays
51
+ sortElementList?: "documentOrder" | "visibility" | "insertionOrder" // Control panel sorting
52
+ logging: {
53
+ logLocation: "controlPanel" | "console" | "both" | "none" // Where to log the Foresight Events
54
+ callbackCompleted: boolean
55
+ callbackInvoked: boolean
56
+ elementDataUpdated: boolean
57
+ elementRegistered: boolean
58
+ elementUnregistered: boolean
59
+ managerSettingsChanged: boolean
60
+ mouseTrajectoryUpdate: boolean
61
+ scrollTrajectoryUpdate: boolean
62
+ }
63
+ }
64
+ ```
65
+
66
+ ### Available Development Tools Settings
67
+
68
+ **TypeScript Type:** `DevelopmentToolsSettings`
69
+
70
+ | Setting | Type | Default | Description |
71
+ | -------------------------------- | ----------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
72
+ | `showDebugger` | `boolean` | `true` | Controls whether the development tools are visible and active |
73
+ | `isControlPanelDefaultMinimized` | `boolean` | `false` | When true, the development tools control panel will be minimized on page load |
74
+ | `showNameTags` | `boolean` | `true` | Shows the element `name` (or `id` if no `name` is given) above registered elements |
75
+ | `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 |
76
+
77
+ ### Logging Configuration
78
+
79
+ **TypeScript Type:** `LogEvents & { logLocation: LoggingLocations }`
80
+
81
+ | Setting | Type | Default | Description |
82
+ | ------------------------ | ------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------- |
83
+ | `logLocation` | `"controlPanel"` \| `"console"` \| `"both"` \| `"none"` | `"controlPanel"` | Where to output the ForesightJS event logs |
84
+ | `callbackCompleted` | `boolean` | `false` | Log when element callbacks finish executing (includes success/error status and execution time) |
85
+ | `callbackInvoked` | `boolean` | `false` | Log when element callbacks are triggered (includes hit type: mouse/keyboard/scroll) |
86
+ | `elementDataUpdated` | `boolean` | `false` | Log when element data changes (bounds updates, visibility changes) |
87
+ | `elementRegistered` | `boolean` | `false` | Log when new elements are registered with ForesightJS |
88
+ | `elementUnregistered` | `boolean` | `false` | Log when elements are unregistered (includes reason: callbackHit/disconnected/apiCall) |
89
+ | `managerSettingsChanged` | `boolean` | `false` | Log when ForesightManager global settings are modified |
90
+ | `mouseTrajectoryUpdate` | `boolean` | `false` | Log real-time mouse trajectory predictions (high frequency - use with caution) |
91
+ | `scrollTrajectoryUpdate` | `boolean` | `false` | Log scroll direction predictions and trajectory updates |
92
+
93
+ ### Usage Example with All Options
94
+
95
+ ```javascript
96
+ import { ForesightManager } from "js.foresight"
97
+ import { ForesightDevtools } from "js.foresight-devtools"
98
+
99
+ // Initialize ForesightJS
100
+ ForesightManager.initialize({
101
+ trajectoryPredictionTime: 100,
102
+ defaultHitSlop: { top: 10, right: 10, bottom: 10, left: 10 },
103
+ enableMousePrediction: true,
104
+ enableTabPrediction: true,
105
+ enableScrollPrediction: true,
106
+ })
107
+
108
+ // Initialize development tools with custom settings
109
+ ForesightDevtools.initialize({
110
+ showDebugger: true,
111
+ isControlPanelDefaultMinimized: false,
112
+ showNameTags: true,
113
+ sortElementList: "visibility",
114
+ logging: {
115
+ logLocation: "controlPanel",
116
+ callbackCompleted: true,
117
+ callbackInvoked: true,
118
+ elementRegistered: true,
119
+ elementUnregistered: true,
120
+ elementDataUpdated: false, // High frequency - keep disabled for performance
121
+ managerSettingsChanged: true,
122
+ mouseTrajectoryUpdate: false, // High frequency - keep disabled for performance
123
+ scrollTrajectoryUpdate: false, // High frequency - keep disabled for performance
124
+ },
125
+ })
126
+
127
+ // Register elements as usual
128
+ ForesightManager.instance.register({
129
+ element: document.getElementById("my-button"),
130
+ callback: () => {
131
+ console.log("Prediction triggered!")
132
+ },
133
+ name: "my-button", // This name will appear in the development tools
134
+ })
135
+ ```
136
+
137
+ ## Development Workflow
138
+
139
+ The development tools are particularly useful when:
140
+
141
+ 1. **Setting up ForesightJS** for the first time in an application
142
+ 2. **Fine-tuning prediction parameters** for specific UI components
143
+ 3. **Debugging callback execution** issues or unexpected behavior
144
+ 4. **Optimizing hit slop areas** for better user experience
145
+ 5. **Understanding prediction accuracy** across different interaction patterns
146
+
147
+ ## Framework Integration
148
+
149
+ Since both ForesightJS and the development tools are framework-agnostic, you can use them together in any JavaScript environment:
150
+
151
+ - React / Next.js
152
+ - Vue / Nuxt
153
+ - Angular
154
+ - Svelte / SvelteKit
155
+ - Vanilla JavaScript
156
+
157
+ ## Requirements
158
+
159
+ - **js.foresight** ^3.0.0 (peer dependency)
160
+
161
+ ## License
162
+
163
+ MIT © [Bart Spaans](https://github.com/spaansba)
164
+
165
+ ## Related
166
+
167
+ - [ForesightJS](https://foresightjs.com/) - The main prediction library
168
+ - [Documentation](https://foresightjs.com/docs) - Comprehensive guides and API reference
169
+ - [GitHub](https://github.com/spaansba/ForesightJS) - Source code and issues
package/dist/index.d.mts CHANGED
@@ -1,5 +1,5 @@
1
1
  import * as lit from 'lit';
2
- import { LitElement, TemplateResult } from 'lit';
2
+ import { LitElement, TemplateResult, PropertyValues } from 'lit';
3
3
  import { ForesightEvent, ForesightElementData, ForesightManagerSettings as ForesightManagerSettings$2 } from 'js.foresight';
4
4
  import { ForesightEvent as ForesightEvent$1, HitSlop as HitSlop$1, UpdatedDataPropertyNames, CallbackHitType, Point, ScrollDirection, ForesightManagerSettings as ForesightManagerSettings$1 } from 'js.foresight/types/types';
5
5
 
@@ -334,6 +334,7 @@ interface PayloadBase {
334
334
  type: SerializedEventType;
335
335
  localizedTimestamp: string;
336
336
  summary: string;
337
+ logId: string;
337
338
  }
338
339
  interface ElementRegisteredPayload extends PayloadBase {
339
340
  type: "elementRegistered";
@@ -401,12 +402,11 @@ type SerializedEventData = ElementRegisteredPayload | ElementUnregisteredPayload
401
402
 
402
403
  declare class SingleLog extends LitElement {
403
404
  static styles: lit.CSSResult[];
404
- private log;
405
+ log: SerializedEventData;
406
+ constructor(log: SerializedEventData);
405
407
  isExpanded: boolean;
406
408
  onToggle: ((logId: string) => void) | undefined;
407
- constructor(log: SerializedEventData & {
408
- logId: string;
409
- });
409
+ protected updated(changedProperties: PropertyValues<this>): void;
410
410
  private serializeLogDataWithoutSummary;
411
411
  private getLogTypeColor;
412
412
  private getEventDisplayName;
@@ -496,7 +496,7 @@ declare class SettingItemRange extends LitElement {
496
496
  private displayValue;
497
497
  private handleRangeInput;
498
498
  private handleRangeChange;
499
- willUpdate(changedProperties: Map<string, any>): void;
499
+ willUpdate(changedProperties: PropertyValues): void;
500
500
  render(): lit.TemplateResult<1>;
501
501
  }
502
502
  declare global {
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import * as lit from 'lit';
2
- import { LitElement, TemplateResult } from 'lit';
2
+ import { LitElement, TemplateResult, PropertyValues } from 'lit';
3
3
  import { ForesightEvent, ForesightElementData, ForesightManagerSettings as ForesightManagerSettings$2 } from 'js.foresight';
4
4
  import { ForesightEvent as ForesightEvent$1, HitSlop as HitSlop$1, UpdatedDataPropertyNames, CallbackHitType, Point, ScrollDirection, ForesightManagerSettings as ForesightManagerSettings$1 } from 'js.foresight/types/types';
5
5
 
@@ -334,6 +334,7 @@ interface PayloadBase {
334
334
  type: SerializedEventType;
335
335
  localizedTimestamp: string;
336
336
  summary: string;
337
+ logId: string;
337
338
  }
338
339
  interface ElementRegisteredPayload extends PayloadBase {
339
340
  type: "elementRegistered";
@@ -401,12 +402,11 @@ type SerializedEventData = ElementRegisteredPayload | ElementUnregisteredPayload
401
402
 
402
403
  declare class SingleLog extends LitElement {
403
404
  static styles: lit.CSSResult[];
404
- private log;
405
+ log: SerializedEventData;
406
+ constructor(log: SerializedEventData);
405
407
  isExpanded: boolean;
406
408
  onToggle: ((logId: string) => void) | undefined;
407
- constructor(log: SerializedEventData & {
408
- logId: string;
409
- });
409
+ protected updated(changedProperties: PropertyValues<this>): void;
410
410
  private serializeLogDataWithoutSummary;
411
411
  private getLogTypeColor;
412
412
  private getEventDisplayName;
@@ -496,7 +496,7 @@ declare class SettingItemRange extends LitElement {
496
496
  private displayValue;
497
497
  private handleRangeInput;
498
498
  private handleRangeChange;
499
- willUpdate(changedProperties: Map<string, any>): void;
499
+ willUpdate(changedProperties: PropertyValues): void;
500
500
  render(): lit.TemplateResult<1>;
501
501
  }
502
502
  declare global {