js.foresight 2.1.5 → 2.2.1

package/README.md

@@ -10,7 +10,7 @@
 [![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/)
 
-ForesightJS is a lightweight JavaScript library with full TypeScript support that predicts user intent based on mouse movements and keyboard navigation. By analyzing cursor 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).
+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).
 
 ### Understanding ForesightJS's Role:
 
@@ -54,11 +54,11 @@ Many routers rely on hover-based prefetching, but this approach completely exclu
 
 ### 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 and keyboard navigation sequences. This allows you to prefetch resources at the optimal time to improve performance, but targeted enough to avoid waste.
+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
 
-Both global and element speicif configuration details can be found [here](https://foresightjs.com/docs/getting_started/config).
+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"
@@ -85,15 +85,9 @@ const { isTouchDevice, unregister } = ForesightManager.instance.register({
 unregister()
 ```
 
-## What About Touch Devices?
-
-ForesightJS focuses on using mouse movement for prefetching, so you'll need your own approach for touch devices like phones and tablets. The `ForesightManager.instance.register()` method returns an `isTouchDevice` boolean that you can use to create this separate logic. You can safely call `register()` even on touch devices, as the Foresight manager will bounce touch devices to avoid unnecessary processing.
-
-An example of what to do with touch devices can be found in the [Next.js](https://foresightjs.com/docs/integrations/nextjs) or [React Router](https://foresightjs.com/docs/integrations/react) ForesightLink components.
-
 ## Integrations
 
-Since ForesightJS is framework agnostic, it can be integrated with any JavaScript framework. While I haven't yet built integrations for every framework, ready-to-use implementations for [Next.js](https://foresightjs.com/docs/integrations/nextjs) and [React Router](https://foresightjs.com/docs/integrations/react) are already available. Sharing integrations for other frameworks/packages is highly appreciated!
+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
 
@@ -103,6 +97,19 @@ ForesightJS can be used bare-bones but also can be configured. For all configura
 
 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)**.

package/dist/index.d.ts

@@ -22,16 +22,45 @@ type ElementBounds = {
     /** The expanded rectangle, including hitSlop, used for interaction detection. */
     expandedRect: Rect;
     /** The original bounding rectangle of the element, as returned by `getBoundingClientRect()`. */
-    originalRect?: DOMRectReadOnly;
+    originalRect?: DOMRectReadOnly | undefined;
     /** The hit slop values applied to this element. */
     hitSlop: Exclude<HitSlop, number>;
 };
 type DebuggerSettings = {
-    /** If the control panel should be minimized on default @default false */
+    /**
+     * Determines if the debugger control panel should be initialized in a minimized state.
+     *
+     * @link https://foresightjs.com/docs/getting_started/debug
+     *
+     * @default false
+     */
     isControlPanelDefaultMinimized?: boolean;
-    /** If we should show the name tags above elements @default false */
+    /**
+     * Determines if name tags should be displayed visually above each registered element.
+     * This is a helpful visual aid for identifying which elements are being tracked.
+     *
+     * @link https://foresightjs.com/docs/getting_started/debug
+     *
+     * @default false
+     */
     showNameTags?: boolean;
+    /**
+     * Specifies the default sorting order for the list of registered elements in the debugger panel.
+     * - `'visibility'`: Sorts elements by their viewport visibility (visible elements first),
+     *   with a secondary documentOrder sort.
+     * - `'documentOrder'`: Sorts elements based on their order of appearance in the
+     *   document's structure (matching the HTML source).
+     * - `'insertionOrder'`: Sorts by registration order.
+     *
+     *
+     * @link https://foresightjs.com/docs/getting_started/debug
+     *
+     * @default 'visibility'
+     *
+     */
+    sortElementList?: SortElementList;
 };
+type SortElementList = "documentOrder" | "visibility" | "insertionOrder";
 /**
  * Represents trajectory hit related data for a foresight element.
  */
@@ -46,7 +75,11 @@ type TrajectoryHitData = {
 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;
-    /** Function to unregister the element, optional to add the elementdata */
+    /** 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;
 };
 /**
@@ -82,22 +115,31 @@ 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;
 };
+/**
+ * Snapshot of the current ForesightManager state
+ */
 type ForesightManagerData = {
-    registeredElements: Map<ForesightElement, ForesightElementData>;
+    registeredElements: ReadonlyMap<ForesightElement, ForesightElementData>;
     globalSettings: Readonly<ForesightManagerSettings>;
     globalCallbackHits: Readonly<CallbackHits>;
-    positionObserverElements: Map<Element, IntersectionObserverEntry> | undefined;
 };
 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
      */
@@ -106,6 +148,8 @@ type BaseForesightManagerSettings = {
      * 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
      */
@@ -113,14 +157,32 @@ type BaseForesightManagerSettings = {
     /**
      * 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
      *
@@ -151,13 +213,21 @@ type BaseForesightManagerSettings = {
 };
 /**
  * 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;
@@ -165,7 +235,18 @@ type ForesightRegisterOptions = {
     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;
 
 /**
@@ -194,6 +275,10 @@ declare class ForesightManager {
     private _globalCallbackHits;
     private _globalSettings;
     private trajectoryPositions;
+    private tabbableElementsCache;
+    private lastFocusedIndex;
+    private predictedScrollPoint;
+    private scrollDirection;
     private domObserver;
     private positionObserver;
     private lastKeyDown;
@@ -256,6 +341,7 @@ declare class ForesightManager {
      */
     private forceUpdateElementBounds;
     private updateElementBounds;
+    private handleScrollPrefetch;
     private handlePositionChange;
     private initializeGlobalListeners;
     private removeGlobalListeners;