js.foresight 3.0.1 → 3.1.1

package/README.md

@@ -1,12 +1,34 @@
-# js.foresight
+# [ForesightJS](https://foresightjs.com/)
 
-The core ForesightJS library package.
+[![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)
 
-A lightweight JavaScript/TypeScript library that predicts user intent based on mouse movements, scroll behavior, and keyboard navigation. Published as `js.foresight` on npm.
+[![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#playground)
 
-**For complete documentation, usage examples, and API reference, see the [main README](../../README.md).**
+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).
 
-## Installation
+### 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, the [ForesightJS DevTools](https://foresightjs.com/docs/getting_started/development_tools) are enabled. Normally, users won't see anything that ForesightJS does except the increased perceived speed from early prefetching._
+
+## Download
 
 ```bash
 pnpm add js.foresight
@@ -15,3 +37,96 @@ 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)
+ForesightManager.initialize({
+  // Optional props (see configuration)
+})
+
+// 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
+  // other optional props (see configuration)
+})
+
+// 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).
+
+## Development Tools
+
+ForesightJS has dedicated [Development Tools](https://github.com/spaansba/ForesightJS-DevTools) created with [Foresight Events](https://foresightjs.com/docs/getting_started/events) that help you understand and tune how foresight is working in your application. This standalone development package provides real-time visualization of mouse trajectory predictions, element bounds, and callback execution. It's particularly helpful when setting up ForesightJS for the first time or when fine-tuning for specific UI components.
+
+```bash
+npm install js.foresight-devtools
+```
+
+See the [development tools documentation](https://foresightjs.com/docs/getting_started/debug) for more details.
+
+## 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
+
+ForesightJS is a newer library, so most AI assistants and LLMs may not have much built-in knowledge about it. To improve their responses, you can provide the following context:
+
+- Use [llms.txt](https://foresightjs.com/llms.txt) for a concise overview of the API and usage patterns.
+- Use [llms-full.txt](https://foresightjs.com/llms-full.txt) for a full markdown version of the docs, ideal for AI tools that support context injection or uploads.
+- All documentation pages are also available in markdown. You can view them by adding .md to the end of any URL, for example: https://foresightjs.com/docs/getting_started.md.
+
+# Contributing
+
+Please see the [contributing guidelines](/CONTRIBUTING.md)

package/dist/{src/types/types.d.ts → index.d.mts}

@@ -1,4 +1,4 @@
-export type Rect = {
+type Rect = {
     top: number;
     left: number;
     right: number;
@@ -8,27 +8,27 @@ export type Rect = {
  * A callback function that is executed when a foresight interaction
  * (e.g., hover, trajectory hit) occurs on a registered element.
  */
-export type ForesightCallback = () => void;
+type ForesightCallback = () => void;
 /**
  * Represents the HTML element that is being tracked by the ForesightManager.
  * This is typically a standard DOM `Element`.
  */
-export type ForesightElement = Element;
+type ForesightElement = Element;
 /**
  * Represents a mouse position captured at a specific point in time.
  * Used for tracking mouse movement history.
  */
-export type MousePosition = {
+type MousePosition = {
     /** The (x, y) coordinates of the mouse. */
     point: Point;
     /** The timestamp (e.g., from `performance.now()`) when this position was recorded. */
     time: number;
 };
-export type Point = {
+type Point = {
     x: number;
     y: number;
 };
-export type TrajectoryPositions = {
+type TrajectoryPositions = {
     positions: MousePosition[];
     currentPoint: Point;
     predictedPoint: Point;
@@ -37,18 +37,18 @@ export type TrajectoryPositions = {
  * Internal type representing the calculated boundaries of a foresight element,
  * including its original dimensions and the expanded hit area.
  */
-export type ElementBounds = {
+type ElementBounds = {
     /** The expanded rectangle, including hitSlop, used for interaction detection. */
-    expandedRect: Rect;
+    expandedRect: Readonly<Rect>;
     /** The original bounding rectangle of the element, as returned by `getBoundingClientRect()`. */
-    originalRect?: DOMRectReadOnly | undefined;
+    originalRect: DOMRectReadOnly;
     /** The hit slop values applied to this element. */
     hitSlop: Exclude<HitSlop, number>;
 };
 /**
  * Represents trajectory hit related data for a foresight element.
  */
-export type TrajectoryHitData = {
+type TrajectoryHitData = {
     /** True if the predicted mouse trajectory has intersected the element's expanded bounds. */
     isTrajectoryHit: boolean;
     /** The timestamp when the last trajectory hit occurred. */
@@ -56,7 +56,7 @@ export type TrajectoryHitData = {
     /** Timeout ID for expiring the trajectory hit state. */
     trajectoryHitExpirationTimeoutId?: ReturnType<typeof setTimeout>;
 };
-export type ForesightRegisterResult = {
+type ForesightRegisterResult = {
     /** Whether the current device is a touch device. This is important as ForesightJS only works based on cursor movement. If the user is using a touch device you should handle prefetching differently  */
     isTouchDevice: boolean;
     /** Whether the user has connection limitations (slow network (2g) or data saver enabled) that should prevent prefetching */
@@ -69,7 +69,7 @@ export type ForesightRegisterResult = {
 /**
  * Represents the data associated with a registered foresight element.
  */
-export type ForesightElementData = Required<Pick<ForesightRegisterOptions, "callback" | "name">> & {
+type ForesightElementData = Required<Pick<ForesightRegisterOptions, "callback" | "name">> & {
     /** The boundary information for the element. */
     elementBounds: ElementBounds;
     /** True if the mouse cursor is currently hovering over the element's expanded bounds. */
@@ -80,30 +80,39 @@ export type ForesightElementData = Required<Pick<ForesightRegisterOptions, "call
     trajectoryHitData: TrajectoryHitData;
     /**
      * Is the element intersecting with the viewport, usefull to track which element we should observe or not
+     * Can be @undefined in the split second the element is registering
      */
     isIntersectingWithViewport: boolean;
     /**
      * The element you registered
      */
     element: ForesightElement;
+    /**
+     * If the element is currently running its callback
+     */
+    isRunningCallback: boolean;
+    /**
+     * For debugging, check if you are registering the same element multiple times.
+     */
+    registerCount: number;
 };
-export type MouseCallbackCounts = {
+type MouseCallbackCounts = {
     hover: number;
     trajectory: number;
 };
-export type TabCallbackCounts = {
+type TabCallbackCounts = {
     reverse: number;
     forwards: number;
 };
-export type ScrollDirection = "down" | "up" | "left" | "right" | "none";
-export type ScrollCallbackCounts = Record<`${Exclude<ScrollDirection, "none">}`, number>;
-export type CallbackHits = {
+type ScrollDirection = "down" | "up" | "left" | "right" | "none";
+type ScrollCallbackCounts = Record<`${Exclude<ScrollDirection, "none">}`, number>;
+type CallbackHits = {
     total: number;
     mouse: MouseCallbackCounts;
     tab: TabCallbackCounts;
     scroll: ScrollCallbackCounts;
 };
-export type HitType = {
+type CallbackHitType = {
     kind: "mouse";
     subType: keyof MouseCallbackCounts;
 } | {
@@ -116,10 +125,11 @@ export type HitType = {
 /**
  * Snapshot of the current ForesightManager state
  */
-export type ForesightManagerData = {
+type ForesightManagerData = {
     registeredElements: ReadonlyMap<ForesightElement, ForesightElementData>;
     globalSettings: Readonly<ForesightManagerSettings>;
     globalCallbackHits: Readonly<CallbackHits>;
+    eventListeners: ReadonlyMap<keyof ForesightEventMap, ForesightEventListener[]>;
 };
 type BaseForesightManagerSettings = {
     /**
@@ -187,33 +197,25 @@ type BaseForesightManagerSettings = {
      * @default 2
      */
     tabOffset: number;
-    /**
-     * A global callback that runs whenever a callback is fired for any
-     * registered element, just after the element's specific callback is fired.
-     *
-     * @param elementData - The ForesightTarget object for the element that triggered the event.
-     * @param managerData - Data about the ForesightManager
-     */
-    onAnyCallbackFired: (elementData: ForesightElementData, managerData: ForesightManagerData) => void;
 };
 /**
  * Configuration options for the ForesightManager
  * @link https://foresightjs.com/docs/getting_started/config#available-global-settings
  */
-export type ForesightManagerSettings = BaseForesightManagerSettings & {
+type ForesightManagerSettings = BaseForesightManagerSettings & {
     defaultHitSlop: Exclude<HitSlop, number>;
 };
 /**
  * Update options for the ForesightManager
  * @link https://foresightjs.com/docs/getting_started/config#available-global-settings
  */
-export type UpdateForsightManagerSettings = BaseForesightManagerSettings & {
+type UpdateForsightManagerSettings = BaseForesightManagerSettings & {
     defaultHitSlop: HitSlop;
 };
 /**
  * Type used to register elements to the foresight manager
  */
-export type ForesightRegisterOptions = {
+type ForesightRegisterOptions = {
     element: ForesightElement;
     callback: ForesightCallback;
     hitSlop?: HitSlop;
@@ -230,43 +232,28 @@ export type ForesightRegisterOptions = {
  *
  * @link https://foresightjs.com/docs/getting_started/typescript#foresightregisteroptionswithoutelement
  */
-export type ForesightRegisterOptionsWithoutElement = Omit<ForesightRegisterOptions, "element">;
+type ForesightRegisterOptionsWithoutElement = Omit<ForesightRegisterOptions, "element">;
 /**
  * Fully invisible "slop" around the element.
  * Basically increases the hover hitbox
  */
-export type HitSlop = Rect | number;
-/**
- * Get all keys in UpdateForsightManagerSettings that are numeric
- */
-export type NumericSettingKeys = {
-    [K in keyof UpdateForsightManagerSettings]: UpdateForsightManagerSettings[K] extends number ? K : never;
-}[keyof UpdateForsightManagerSettings];
-/**
- * Get all keys in UpdateForsightManagerSettings that are boolean
- */
-export type ManagerBooleanSettingKeys = {
-    [K in keyof UpdateForsightManagerSettings]: UpdateForsightManagerSettings[K] extends boolean ? K : never;
-}[keyof UpdateForsightManagerSettings];
-export interface ForesightEventMap {
+type HitSlop = Rect | number;
+interface ForesightEventMap {
     elementRegistered: ElementRegisteredEvent;
     elementUnregistered: ElementUnregisteredEvent;
     elementDataUpdated: ElementDataUpdatedEvent;
-    callbackFired: CallbackFiredEvent;
+    callbackInvoked: CallbackInvokedEvent;
+    callbackCompleted: CallbackCompletedEvent;
     mouseTrajectoryUpdate: MouseTrajectoryUpdateEvent;
     scrollTrajectoryUpdate: ScrollTrajectoryUpdateEvent;
     managerSettingsChanged: ManagerSettingsChangedEvent;
 }
-export type ForesightEventType = keyof ForesightEventMap;
-export interface ForesightEvent {
-    type: ForesightEventType;
-    timestamp: number;
-}
-export interface ElementRegisteredEvent extends ForesightEvent {
+type ForesightEvent = "elementRegistered" | "elementUnregistered" | "elementDataUpdated" | "callbackInvoked" | "callbackCompleted" | "mouseTrajectoryUpdate" | "scrollTrajectoryUpdate" | "managerSettingsChanged";
+interface ElementRegisteredEvent extends ForesightBaseEvent {
     type: "elementRegistered";
     elementData: ForesightElementData;
 }
-export interface ElementUnregisteredEvent extends ForesightEvent {
+interface ElementUnregisteredEvent extends ForesightBaseEvent {
     type: "elementUnregistered";
     elementData: ForesightElementData;
     unregisterReason: ElementUnregisteredReason;
@@ -277,33 +264,135 @@ export interface ElementUnregisteredEvent extends ForesightEvent {
  * - `disconnected`: The element was automatically unregistered because it was removed from the DOM.
  * - `apiCall`: The developer manually called the `unregister()` function for the element.
  */
-export type ElementUnregisteredReason = "callbackHit" | "disconnected" | "apiCall";
-export interface ElementDataUpdatedEvent extends ForesightEvent {
+type ElementUnregisteredReason = "callbackHit" | "disconnected" | "apiCall";
+interface ElementDataUpdatedEvent extends Omit<ForesightBaseEvent, "timestamp"> {
     type: "elementDataUpdated";
     elementData: ForesightElementData;
-    updatedProp: "bounds" | "visibility";
+    updatedProps: UpdatedDataPropertyNames[];
 }
-export interface CallbackFiredEvent extends ForesightEvent {
-    type: "callbackFired";
+type UpdatedDataPropertyNames = "bounds" | "visibility";
+interface CallbackInvokedEvent extends ForesightBaseEvent {
+    type: "callbackInvoked";
     elementData: ForesightElementData;
-    hitType: HitType;
-    managerData: ForesightManagerData;
+    hitType: CallbackHitType;
+}
+interface CallbackCompletedEventBase extends ForesightBaseEvent {
+    type: "callbackCompleted";
+    elementData: ForesightElementData;
+    hitType: CallbackHitType;
+    elapsed: number;
 }
-export interface MouseTrajectoryUpdateEvent extends ForesightEvent {
+type CallbackCompletedEvent = CallbackCompletedEventBase & ({
+    status: "success";
+} | {
+    status: "error";
+    errorMessage: string;
+});
+interface MouseTrajectoryUpdateEvent extends Omit<ForesightBaseEvent, "timestamp"> {
     type: "mouseTrajectoryUpdate";
     trajectoryPositions: TrajectoryPositions;
     predictionEnabled: boolean;
 }
-export interface ScrollTrajectoryUpdateEvent extends ForesightEvent {
+interface ScrollTrajectoryUpdateEvent extends Omit<ForesightBaseEvent, "timestamp"> {
     type: "scrollTrajectoryUpdate";
     currentPoint: Point;
     predictedPoint: Point;
+    scrollDirection: ScrollDirection;
 }
-export interface ManagerSettingsChangedEvent extends ForesightEvent {
+interface ManagerSettingsChangedEvent extends ForesightBaseEvent {
     type: "managerSettingsChanged";
     managerData: ForesightManagerData;
+    updatedSettings: UpdatedManagerSetting[];
+}
+type UpdatedManagerSetting = {
+    [K in keyof ForesightManagerSettings]: {
+        setting: K;
+        newValue: ForesightManagerSettings[K];
+        oldValue: ForesightManagerSettings[K];
+    };
+}[keyof ForesightManagerSettings];
+type ForesightEventListener<K extends ForesightEvent = ForesightEvent> = (event: ForesightEventMap[K]) => void;
+interface ForesightBaseEvent {
+    type: ForesightEvent;
+    timestamp: number;
+}
+
+/**
+ * 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}.
+ */
+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 rafId;
+    private pendingMouseEvent;
+    private eventListeners;
+    private constructor();
+    static initialize(props?: Partial<UpdateForsightManagerSettings>): ForesightManager;
+    addEventListener<K extends ForesightEvent>(eventType: K, listener: ForesightEventListener<K>, options?: {
+        signal?: AbortSignal;
+    }): (() => void) | undefined;
+    removeEventListener<K extends ForesightEvent>(eventType: K, listener: ForesightEventListener<K>): 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;
+    private handleMouseMove;
+    private processMouseMovement;
+    /**
+     * 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 handlePositionChange;
+    private handlePositionChangeDataUpdates;
+    private handleScrollPrefetch;
+    private initializeGlobalListeners;
+    private removeGlobalListeners;
 }
-export type ForesightEventData = ElementRegisteredEvent | ElementUnregisteredEvent | ElementDataUpdatedEvent | CallbackFiredEvent | MouseTrajectoryUpdateEvent | ScrollTrajectoryUpdateEvent | ManagerSettingsChangedEvent;
-export type ForesightEventListener = (event: ForesightEventData) => void;
-export {};
-//# sourceMappingURL=types.d.ts.map
+
+export { type CallbackCompletedEvent, type CallbackHitType, type CallbackHits, type CallbackInvokedEvent, type ElementDataUpdatedEvent, type ElementRegisteredEvent, type ElementUnregisteredEvent, type ForesightElement, type ForesightElementData, type ForesightEvent, ForesightManager, type ForesightManagerSettings, type Rect as ForesightRect, type ForesightRegisterOptions, type ForesightRegisterOptionsWithoutElement, type ForesightRegisterResult, type HitSlop, type ManagerSettingsChangedEvent, type MouseTrajectoryUpdateEvent, type ScrollTrajectoryUpdateEvent, type UpdateForsightManagerSettings, type UpdatedManagerSetting };