js.foresight-devtools 0.0.1 → 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bart Spaans
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,14 +1,14 @@
-# ForesightJS Debugger
+# ForesightJS Development Tools
 
-[![npm version](https://img.shields.io/npm/v/@js.foresight/debugger.svg)](https://www.npmjs.com/package/@js.foresight/debugger)
+[![npm version](https://img.shields.io/npm/v/js.foresight-devtools.svg)](https://www.npmjs.com/package/js.foresight-devtools)
 [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Visual debugging 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.
+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.
 
-## What is the ForesightJS Debugger?
+## What are the ForesightJS Development Tools?
 
-The ForesightJS Debugger is a plugin development tool that provides visual debugging capabilities for ForesightJS implementations. It helps developers understand and tune how ForesightJS is working in their applications by providing real-time visualization of:
+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:
 
 - **Mouse trajectory predictions** - See predicted cursor paths and intersection points
 - **Element bounds and hit slop areas** - Visualize registered elements and their interaction zones
@@ -16,16 +16,16 @@ The ForesightJS Debugger is a plugin development tool that provides visual debug
 - **Callback execution** - Monitor when and why prediction callbacks fire
 - **Real-time settings control** - Adjust ForesightJS parameters on the fly
 
-![ForesightJS Debugger Demo](https://github.com/user-attachments/assets/36c81a82-fee7-43d6-ba1e-c48214136f90)
+![ForesightJS Development Tools Demo](https://github.com/user-attachments/assets/36c81a82-fee7-43d6-ba1e-c48214136f90)
 
 ## Installation
 
 ```bash
-npm install js.foresight-devtools
+pnpm add -D js.foresight-devtools
 # or
-pnpm add js.foresight-devtools
+npm install -D js.foresight-devtools
 # or
-yarn add js.foresight-devtools
+yarn add -D js.foresight-devtools
 ```
 
 ## Basic Usage
@@ -37,14 +37,14 @@ import { ForesightDebugger } from "js.foresight-devtools"
 // Initialize ForesightJS
 ForesightManager.initialize()
 
-// Initialize debugger
+// Initialize development tools
 ForesightDebugger.initialize(ForesightManager.instance)
 ```
 
 ## Configuration Options
 
 ```typescript
-type DebuggerSettings = {
+type DevelopmentToolsSettings = {
   showDebugger?: boolean
   isControlPanelDefaultMinimized?: boolean
   showNameTags?: boolean // Show element names on overlays
@@ -52,9 +52,53 @@ type DebuggerSettings = {
 }
 ```
 
+### Available Development Tools Settings
+
+**TypeScript Type:** `DevelopmentToolsSettings`
+
+| Setting                          | Type              | Default      | Description                                                                                                                                                                       |
+| -------------------------------- | ----------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `showDebugger`                   | `boolean`         | `true`       | Controls whether the development tools are visible and active                                                                                                                     |
+| `isControlPanelDefaultMinimized` | `boolean`         | `false`      | When true, the development tools control panel will be minimized on page load                                                                                                     |
+| `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 |
+
+### Usage Example with All Options
+
+```javascript
+import { ForesightManager } from "js.foresight"
+import { ForesightDebugger } from "js.foresight-devtools"
+
+// Initialize ForesightJS
+ForesightManager.initialize({
+  trajectoryPredictionTime: 100,
+  defaultHitSlop: { top: 10, right: 10, bottom: 10, left: 10 },
+  enableMousePrediction: true,
+  enableTabPrediction: true,
+  enableScrollPrediction: true,
+})
+
+// Initialize development tools with custom settings
+ForesightDebugger.initialize(ForesightManager.instance, {
+  showDebugger: true,
+  isControlPanelDefaultMinimized: false,
+  showNameTags: true,
+  sortElementList: "visibility",
+})
+
+// Register elements as usual
+ForesightManager.instance.register({
+  element: document.getElementById("my-button"),
+  callback: () => {
+    console.log("Prediction triggered!")
+  },
+  name: "my-button", // This name will appear in the development tools
+})
+```
+
 ## Development Workflow
 
-The debugger is particularly useful when:
+The development tools are particularly useful when:
 
 1. **Setting up ForesightJS** for the first time in an application
 2. **Fine-tuning prediction parameters** for specific UI components
@@ -64,7 +108,7 @@ The debugger is particularly useful when:
 
 ## Framework Integration
 
-Since both ForesightJS and the debugger are framework-agnostic, you can use them together in any JavaScript environment:
+Since both ForesightJS and the development tools are framework-agnostic, you can use them together in any JavaScript environment:
 
 - React / Next.js
 - Vue / Nuxt