js.foresight 3.0.0 → 3.1.0

package/README.md

@@ -26,7 +26,7 @@ You supply the **What** and **How** inside your `callback` when you register an
 ### [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._
+_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
 
@@ -64,10 +64,8 @@ This basic example is in vanilla JS, ofcourse most people will use ForesightJS w
 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
+  // Optional props (see configuration)
 })
 
 // Register an element to be tracked
@@ -79,6 +77,7 @@ const { isTouchDevice, unregister } = ForesightManager.instance.register({
     // 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:
@@ -93,9 +92,15 @@ Since ForesightJS is framework agnostic, it can be integrated with any JavaScrip
 
 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
+## Development Tools
 
-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.
+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?
 
@@ -120,16 +125,6 @@ Since ForesightJS is a relatively new and unknown library, most AI assistants an
 
 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/index.d.mts

@@ -0,0 +1,398 @@
+type Rect = {
+    top: number;
+    left: number;
+    right: number;
+    bottom: number;
+};
+/**
+ * A callback function that is executed when a foresight interaction
+ * (e.g., hover, trajectory hit) occurs on a registered element.
+ */
+type ForesightCallback = () => void;
+/**
+ * Represents the HTML element that is being tracked by the ForesightManager.
+ * This is typically a standard DOM `Element`.
+ */
+type ForesightElement = Element;
+/**
+ * Represents a mouse position captured at a specific point in time.
+ * Used for tracking mouse movement history.
+ */
+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;
+};
+type Point = {
+    x: number;
+    y: number;
+};
+type TrajectoryPositions = {
+    positions: MousePosition[];
+    currentPoint: Point;
+    predictedPoint: Point;
+};
+/**
+ * Internal type representing the calculated boundaries of a foresight element,
+ * including its original dimensions and the expanded hit area.
+ */
+type ElementBounds = {
+    /** The expanded rectangle, including hitSlop, used for interaction detection. */
+    expandedRect: Readonly<Rect>;
+    /** The original bounding rectangle of the element, as returned by `getBoundingClientRect()`. */
+    originalRect: DOMRectReadOnly;
+    /** The hit slop values applied to this element. */
+    hitSlop: Exclude<HitSlop, number>;
+};
+/**
+ * Represents trajectory hit related data for a foresight element.
+ */
+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. */
+    trajectoryHitTime: number;
+    /** Timeout ID for expiring the trajectory hit state. */
+    trajectoryHitExpirationTimeoutId?: ReturnType<typeof setTimeout>;
+};
+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 */
+    isLimitedConnection: boolean;
+    /** Whether ForesightJS will actively track this element. False if touch device or limited connection, true otherwise */
+    isRegistered: boolean;
+    /** Function to unregister the element */
+    unregister: () => void;
+};
+/**
+ * Represents the data associated with a registered foresight element.
+ */
+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. */
+    isHovering: boolean;
+    /**
+     * Represents trajectory hit related data for a foresight element. Only used for the manager
+     */
+    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;
+};
+type MouseCallbackCounts = {
+    hover: number;
+    trajectory: number;
+};
+type TabCallbackCounts = {
+    reverse: number;
+    forwards: number;
+};
+type ScrollDirection = "down" | "up" | "left" | "right" | "none";
+type ScrollCallbackCounts = Record<`${Exclude<ScrollDirection, "none">}`, number>;
+type CallbackHits = {
+    total: number;
+    mouse: MouseCallbackCounts;
+    tab: TabCallbackCounts;
+    scroll: ScrollCallbackCounts;
+};
+type CallbackHitType = {
+    kind: "mouse";
+    subType: keyof MouseCallbackCounts;
+} | {
+    kind: "tab";
+    subType: keyof TabCallbackCounts;
+} | {
+    kind: "scroll";
+    subType: keyof ScrollCallbackCounts;
+};
+/**
+ * Snapshot of the current ForesightManager state
+ */
+type ForesightManagerData = {
+    registeredElements: ReadonlyMap<ForesightElement, ForesightElementData>;
+    globalSettings: Readonly<ForesightManagerSettings>;
+    globalCallbackHits: Readonly<CallbackHits>;
+    eventListeners: ReadonlyMap<keyof ForesightEventMap, ForesightEventListener[]>;
+};
+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>;
+};
+/**
+ * Update options for the ForesightManager
+ * @link https://foresightjs.com/docs/getting_started/config#available-global-settings
+ */
+type UpdateForsightManagerSettings = BaseForesightManagerSettings & {
+    defaultHitSlop: HitSlop;
+};
+/**
+ * Type used to register elements to the foresight manager
+ */
+type ForesightRegisterOptions = {
+    element: ForesightElement;
+    callback: ForesightCallback;
+    hitSlop?: HitSlop;
+    /**
+     * @deprecated will be removed in V4.0
+     */
+    unregisterOnCallback?: boolean;
+    name?: string;
+};
+/**
+ * Usefull for if you want to create a custom button component in a modern framework (for example React).
+ * And you want to have the ForesightRegisterOptions used in ForesightManager.instance.register({})
+ * without the element as the element will be the ref of the component.
+ *
+ * @link https://foresightjs.com/docs/getting_started/typescript#foresightregisteroptionswithoutelement
+ */
+type ForesightRegisterOptionsWithoutElement = Omit<ForesightRegisterOptions, "element">;
+/**
+ * Fully invisible "slop" around the element.
+ * Basically increases the hover hitbox
+ */
+type HitSlop = Rect | number;
+interface ForesightEventMap {
+    elementRegistered: ElementRegisteredEvent;
+    elementUnregistered: ElementUnregisteredEvent;
+    elementDataUpdated: ElementDataUpdatedEvent;
+    callbackInvoked: CallbackInvokedEvent;
+    callbackCompleted: CallbackCompletedEvent;
+    mouseTrajectoryUpdate: MouseTrajectoryUpdateEvent;
+    scrollTrajectoryUpdate: ScrollTrajectoryUpdateEvent;
+    managerSettingsChanged: ManagerSettingsChangedEvent;
+}
+type ForesightEvent = "elementRegistered" | "elementUnregistered" | "elementDataUpdated" | "callbackInvoked" | "callbackCompleted" | "mouseTrajectoryUpdate" | "scrollTrajectoryUpdate" | "managerSettingsChanged";
+interface ElementRegisteredEvent extends ForesightBaseEvent {
+    type: "elementRegistered";
+    elementData: ForesightElementData;
+}
+interface ElementUnregisteredEvent extends ForesightBaseEvent {
+    type: "elementUnregistered";
+    elementData: ForesightElementData;
+    unregisterReason: ElementUnregisteredReason;
+}
+/**
+ * The reason an element was unregistered from ForesightManager's tracking.
+ * - `callbackHit`: The element was automatically unregistered after its callback fired.
+ * - `disconnected`: The element was automatically unregistered because it was removed from the DOM.
+ * - `apiCall`: The developer manually called the `unregister()` function for the element.
+ */
+type ElementUnregisteredReason = "callbackHit" | "disconnected" | "apiCall";
+interface ElementDataUpdatedEvent extends Omit<ForesightBaseEvent, "timestamp"> {
+    type: "elementDataUpdated";
+    elementData: ForesightElementData;
+    updatedProps: UpdatedDataPropertyNames[];
+}
+type UpdatedDataPropertyNames = "bounds" | "visibility";
+interface CallbackInvokedEvent extends ForesightBaseEvent {
+    type: "callbackInvoked";
+    elementData: ForesightElementData;
+    hitType: CallbackHitType;
+}
+interface CallbackCompletedEventBase extends ForesightBaseEvent {
+    type: "callbackCompleted";
+    elementData: ForesightElementData;
+    hitType: CallbackHitType;
+    elapsed: number;
+}
+type CallbackCompletedEvent = CallbackCompletedEventBase & ({
+    status: "success";
+} | {
+    status: "error";
+    errorMessage: string;
+});
+interface MouseTrajectoryUpdateEvent extends Omit<ForesightBaseEvent, "timestamp"> {
+    type: "mouseTrajectoryUpdate";
+    trajectoryPositions: TrajectoryPositions;
+    predictionEnabled: boolean;
+}
+interface ScrollTrajectoryUpdateEvent extends Omit<ForesightBaseEvent, "timestamp"> {
+    type: "scrollTrajectoryUpdate";
+    currentPoint: Point;
+    predictedPoint: Point;
+    scrollDirection: ScrollDirection;
+}
+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 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 };