js.foresight 2.2.3 → 3.0.1

package/README.md

@@ -1,34 +1,12 @@
-# [ForesightJS](https://foresightjs.com/)
+# js.foresight
 
-[![npm version](https://img.shields.io/npm/v/js.foresight.svg)](https://www.npmjs.com/package/js.foresight)
-[![npm downloads](https://img.shields.io/npm/dt/js.foresight.svg)](https://www.npmjs.com/package/js.foresight)
-[![Bundle Size](https://img.shields.io/bundlephobia/minzip/js.foresight)](https://bundlephobia.com/package/js.foresight)
-[![GitHub stars](https://img.shields.io/github/stars/spaansba/ForesightJS.svg?style=social&label=Star)](https://github.com/spaansba/ForesightJS)
-[![GitHub last commit](https://img.shields.io/github/last-commit/spaansba/ForesightJS)](https://github.com/spaansba/ForesightJS/commits)
+The core ForesightJS library package.
 
-[![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)
-[![Demo](https://img.shields.io/badge/demo-live-blue)](https://foresightjs.com/)
+A lightweight JavaScript/TypeScript library that predicts user intent based on mouse movements, scroll behavior, and keyboard navigation. Published as `js.foresight` on npm.
 
-ForesightJS is a lightweight JavaScript library with full TypeScript support that predicts user intent based on mouse movements, scroll and keyboard navigation. By analyzing cursor/scroll trajectory and tab sequences, it anticipates which elements a user is likely to interact with, allowing developers to trigger actions before the actual hover or click occurs (for example prefetching).
+**For complete documentation, usage examples, and API reference, see the [main README](../../README.md).**
 
-### Understanding ForesightJS's Role:
-
-When you over simplify prefetching it exists of three parts.
-
-- **What** resource or data to load
-- **How** the loading method and caching strategy is
-- **When** the optimal moment to start fetching is
-
-ForesightJS takes care of the **When** by predicting user intent with mouse trajectory and tab navigation.
-You supply the **What** and **How** inside your `callback` when you register an element.
-
-### [Playground](https://foresightjs.com/)
-
-![](https://github.com/user-attachments/assets/36c81a82-fee7-43d6-ba1e-c48214136f90)
-_In the GIF above, [debug mode](https://foresightjs.com/docs/getting_started/debug) is on. Normally, users won't see anything that ForesightJS does except the increased perceived speed from early prefetching._
-
-## Download
+## Installation
 
 ```bash
 pnpm add js.foresight
@@ -37,99 +15,3 @@ npm install js.foresight
 # or
 yarn add js.foresight
 ```
-
-## Which problems does ForesightJS solve?
-
-### Problem 1: On-Hover Prefetching Still Has Latency
-
-Traditional hover-based prefetching only triggers after the user's cursor reaches an element. This approach wastes the critical 100-200ms window between when a user begins moving toward a target and when the hover event actually fires.
-
-### Problem 2: Viewport-Based Prefetching is Wasteful
-
-Many modern frameworks (like Next.js) automatically prefetch resources for all links that enter the viewport. While well-intentioned, this creates significant overhead since users typically interact with only a small fraction of visible elements. Simply scrolling up and down the Next.js homepage can trigger **_1.59MB_** of unnecessary prefetch requests.
-
-### Problem 3: Hover-Based Prefetching Excludes Keyboard Users
-
-Many routers rely on hover-based prefetching, but this approach completely excludes keyboard users since keyboard navigation never triggers hover events. This means keyboard users miss out on the performance benefits that mouse users get from hover-based prefetching.
-
-### The ForesightJS Solution
-
-ForesightJS bridges the gap between wasteful viewport prefetching and basic hover prefetching. The `ForesightManager` predicts user interactions by analyzing mouse trajectory patterns, scroll direction and keyboard navigation sequences. This allows you to prefetch resources at the optimal time to improve performance, but targeted enough to avoid waste.
-
-## Basic Usage Example
-
-This basic example is in vanilla JS, ofcourse most people will use ForesightJS with a framework. You can read about framework integrations in the [docs](https://foresightjs.com/docs/integrations).
-
-```javascript
-import { ForesightManager } from "foresightjs"
-
-// Initialize the manager if you want custom global settings (do this once at app startup)
-// If you dont want global settings, you dont have to initialize the manager
-ForesightManager.initialize({
-  debug: false, // Set to true to see visualization
-  trajectoryPredictionTime: 80, // How far ahead (in milliseconds) to predict the mouse trajectory
-})
-
-// Register an element to be tracked
-const myButton = document.getElementById("my-button")
-
-const { isTouchDevice, unregister } = ForesightManager.instance.register({
-  element: myButton,
-  callback: () => {
-    // This is where your prefetching logic goes
-  },
-  hitSlop: 20, // Optional: "hit slop" in pixels. Overwrites defaultHitSlop
-})
-
-// Later, when done with this element:
-unregister()
-```
-
-## Integrations
-
-Since ForesightJS is framework agnostic, it can be integrated with any JavaScript framework. While I haven't yet built [integrations](https://foresightjs.com/docs/integrations) for every framework, ready-to-use implementations for [Next.js](https://foresightjs.com/docs/integrations/react/nextjs) and [React Router](https://foresightjs.com/docs/integrations/react/react-router) are already available. Sharing integrations for other frameworks/packages is highly appreciated!
-
-## Configuration
-
-ForesightJS can be used bare-bones but also can be configured. For all configuration possibilities you can reference the [docs](https://foresightjs.com/docs/getting_started/config).
-
-## Debugging Visualization
-
-ForesightJS includes a [Visual Debugging](https://foresightjs.com/docs/getting_started/debug) system that helps you understand and tune how foresight is working in your application. This is particularly helpful when setting up ForesightJS for the first time or when fine-tuning for specific UI components.
-
-## What About Touch Devices and Slow Connections?
-
-Since ForesightJS relies on the keyboard/mouse it will not register elements for touch devices. For limited connections (2G or data-saver mode), we respect the user's preference to minimize data usage and skip registration aswell.
-
-The `ForesightManager.instance.register()` method returns these properties:
-
-- `isTouchDevice` - true if user is on a touch device
-- `isLimitedConnection` - true when user is on a 2G connection or has data-saver enabled
-- `isRegistered` - true if element was actually registered
-
-With these properties you could create your own fallback prefetching methods if required. For example if the user is on a touch device you could prefetch based on viewport.
-An example of this can be found in the [Next.js](https://foresightjs.com/docs/integrations/react/nextjs) or [React Router](https://foresightjs.com/docs/integrations/react/react-router) ForesightLink components.
-
-## How Does ForesightJS Work?
-
-For a detailed technical explanation of its prediction algorithms and internal architecture, see the **[Behind the Scenes documentation](https://foresightjs.com/docs/Behind_the_Scenes)**.
-
-## Providing Context to AI Tools
-
-Since ForesightJS is a relatively new and unknown library, most AI assistants and large language models (LLMs) may not have comprehensive knowledge about it in their training data. To help AI assistants better understand and work with ForesightJS, you can provide them with context from our [llms.txt](https://foresightjs.com/llms.txt) page, which contains structured information about the library's API and usage patterns.
-
-Additionally, every page in the documentation is available in markdown format (try adding .md to any documentation URL). You can share these markdown files as context with AI assistants, though all this information is also consolidated in the llms.txt file for convenience.
-
-## Future of ForesightJS
-
-ForesightJS will continue to evolve with a focus on staying as lightweight and performant as possible. To achieve this the plan is to decouple the debugger and make it its own standalone dev package, reducing the core library size even further.
-
-Beyond size optimization, performance remains central to every development decision. Each release will focus on improving prediction accuracy while reducing computational overhead, ensuring ForesightJS stays practical for production environments. We also want to move as much processing as possible off the main thread to keep user interfaces responsive.
-
-These performance improvements go hand in hand with expanding accessibility across different development environments. The documentation will grow to include more framework integrations beyond the current Next.js and React Router implementations, making ForesightJS accessible to developers working with different technology stacks and routing solutions.
-
-All of these efforts benefit from community input. [Contributions](/CONTRIBUTING.md) are always welcome, whether for new framework integrations, performance improvements, or feature ideas.
-
-# Contributing
-
-Please see the [contributing guidelines](/CONTRIBUTING.md)

package/dist/Manager/ForesightManager.d.ts

@@ -0,0 +1,89 @@
+import type { ForesightElement, ForesightElementData, ForesightEventMap, ForesightEventType, ForesightManagerData, ForesightRegisterOptions, ForesightRegisterResult, UpdateForsightManagerSettings } from "../types/types";
+/**
+ * Manages the prediction of user intent based on mouse trajectory and element interactions.
+ *
+ * ForesightManager is a singleton class responsible for:
+ * - Registering HTML elements to monitor.
+ * - Tracking mouse movements and predicting future cursor positions.
+ * - Detecting when a predicted trajectory intersects with a registered element's bounds.
+ * - Invoking callbacks associated with elements upon predicted or actual interaction.
+ * - Optionally unregistering elements after their callback is triggered.
+ * - Handling global settings for prediction behavior (e.g., history size, prediction time).
+ * - Automatically updating element bounds on resize using {@link ResizeObserver}.
+ * - Automatically unregistering elements removed from the DOM using {@link MutationObserver}.
+ * - Detecting broader layout shifts via {@link MutationObserver} to update element positions.
+ *
+ * It should be initialized once using {@link ForesightManager.initialize} and then
+ * accessed via the static getter {@link ForesightManager.instance}.
+ */
+export declare class ForesightManager {
+    private static manager;
+    private elements;
+    private isSetup;
+    private _globalCallbackHits;
+    private _globalSettings;
+    private trajectoryPositions;
+    private tabbableElementsCache;
+    private lastFocusedIndex;
+    private predictedScrollPoint;
+    private scrollDirection;
+    private domObserver;
+    private positionObserver;
+    private lastKeyDown;
+    private globalListenersController;
+    private eventListeners;
+    private constructor();
+    static initialize(props?: Partial<UpdateForsightManagerSettings>): ForesightManager;
+    addEventListener<K extends ForesightEventType>(eventType: K, listener: (event: ForesightEventMap[K]) => void, options?: {
+        signal?: AbortSignal;
+    }): (() => void) | undefined;
+    removeEventListener<K extends ForesightEventType>(eventType: K, listener: (event: ForesightEventMap[K]) => void): void;
+    logSubscribers(): void;
+    private emit;
+    get getManagerData(): Readonly<ForesightManagerData>;
+    static get isInitiated(): Readonly<boolean>;
+    static get instance(): ForesightManager;
+    get registeredElements(): ReadonlyMap<ForesightElement, ForesightElementData>;
+    register({ element, callback, hitSlop, name, }: ForesightRegisterOptions): ForesightRegisterResult;
+    private unregister;
+    private updateNumericSettings;
+    private updateBooleanSetting;
+    alterGlobalSettings(props?: Partial<UpdateForsightManagerSettings>): void;
+    private forceUpdateAllElementBounds;
+    private updatePointerState;
+    /**
+     * Processes elements that unregister after a single callback.
+     *
+     * This is a "fire-and-forget" handler. Its only goal is to trigger the
+     * callback once. It does so if the mouse trajectory is predicted to hit the
+     * element (if prediction is on) OR if the mouse physically hovers over it.
+     * It does not track state, as the element is immediately unregistered.
+     *
+     * @param elementData - The data object for the foresight element.
+     * @param element - The HTML element being interacted with.
+     */
+    private handleCallbackInteraction;
+    private handleMouseMove;
+    /**
+     * Detects when registered elements are removed from the DOM and automatically unregisters them to prevent stale references.
+     *
+     * @param mutationsList - Array of MutationRecord objects describing the DOM changes
+     *
+     */
+    private handleDomMutations;
+    private handleKeyDown;
+    private handleFocusIn;
+    private updateHitCounters;
+    private callCallback;
+    /**
+     * ONLY use this function when you want to change the rect bounds via code, if the rects are changing because of updates in the DOM do not use this function.
+     * We need an observer for that
+     */
+    private forceUpdateElementBounds;
+    private updateElementBounds;
+    private handleScrollPrefetch;
+    private handlePositionChange;
+    private initializeGlobalListeners;
+    private removeGlobalListeners;
+}
+//# sourceMappingURL=ForesightManager.d.ts.map

package/dist/Manager/ForesightManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ForesightManager.d.ts","sourceRoot":"","sources":["../../src/Manager/ForesightManager.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAGV,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EAEpB,wBAAwB,EACxB,uBAAuB,EAOvB,6BAA6B,EAC9B,MAAM,gBAAgB,CAAA;AAkCvB;;;;;;;;;;;;;;;;GAgBG;AAEH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,OAAO,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAyD;IACzE,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,mBAAmB,CAgB1B;IACD,OAAO,CAAC,eAAe,CAmBtB;IACD,OAAO,CAAC,mBAAmB,CAI1B;IAED,OAAO,CAAC,qBAAqB,CAAyB;IACtD,OAAO,CAAC,gBAAgB,CAAsB;IAE9C,OAAO,CAAC,oBAAoB,CAAqB;IACjD,OAAO,CAAC,eAAe,CAA+B;IACtD,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,gBAAgB,CAAgC;IAExD,OAAO,CAAC,WAAW,CAA6B;IAGhD,OAAO,CAAC,yBAAyB,CAA+B;IAEhE,OAAO,CAAC,cAAc,CAA+D;IAGrF,OAAO;WAEO,UAAU,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,6BAA6B,CAAC,GAAG,gBAAgB;IAUnF,gBAAgB,CAAC,CAAC,SAAS,kBAAkB,EAClD,SAAS,EAAE,CAAC,EACZ,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,IAAI,EAC/C,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE;IAa7B,mBAAmB,CAAC,CAAC,SAAS,kBAAkB,EACrD,SAAS,EAAE,CAAC,EACZ,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,IAAI,GAC9C,IAAI;IAWA,cAAc,IAAI,IAAI;IA+B7B,OAAO,CAAC,IAAI;IAaZ,IAAW,cAAc,IAAI,QAAQ,CAAC,oBAAoB,CAAC,CAM1D;IAED,WAAkB,WAAW,IAAI,QAAQ,CAAC,OAAO,CAAC,CAEjD;IAED,WAAkB,QAAQ,IAAI,gBAAgB,CAE7C;IAED,IAAW,kBAAkB,IAAI,WAAW,CAAC,gBAAgB,EAAE,oBAAoB,CAAC,CAEnF;IAEM,QAAQ,CAAC,EACd,OAAO,EACP,QAAQ,EACR,OAAO,EACP,IAAI,GACL,EAAE,wBAAwB,GAAG,uBAAuB;IAyErD,OAAO,CAAC,UAAU;IA6BlB,OAAO,CAAC,qBAAqB;IAe7B,OAAO,CAAC,oBAAoB;IAWrB,mBAAmB,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,6BAA6B,CAAC,GAAG,IAAI;IA2FhF,OAAO,CAAC,2BAA2B;IAUnC,OAAO,CAAC,kBAAkB;IAY1B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,yBAAyB;IAoBjC,OAAO,CAAC,eAAe,CAiBtB;IAED;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB,CAezB;IAMD,OAAO,CAAC,aAAa,CAIpB;IAED,OAAO,CAAC,aAAa,CAgDpB;IAED,OAAO,CAAC,iBAAiB;IAmBzB,OAAO,CAAC,YAAY;IAiBpB;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAwBhC,OAAO,CAAC,mBAAmB;IAmB3B,OAAO,CAAC,oBAAoB;IAuD5B,OAAO,CAAC,oBAAoB,CAyB3B;IAED,OAAO,CAAC,yBAAyB;IAgCjC,OAAO,CAAC,qBAAqB;CAW9B"}