js.foresight
Version:
Predicts mouse trajectory to trigger actions as users approach elements, enabling anticipatory UI updates or pre-loading. Made with vanilla javascript and usable in every framework.
89 lines • 4.29 kB
TypeScript
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