scroll-tracking-walkeros/dist/index.d.mts

Custom scroll tracking used as an additional source for WalkerOS.

/**
 * Reports the current scroll position relative to the height of the article or document body.
 *
 * This function attempts to find an element with the ID "articlebody" and use its height
 * as the reference for calculating scroll percentage. If no such element is found,
 * it falls back to using the entire "document.body".
 *
 * The returned "scrollPercent" is a normalized value between 0 and 1, representing the
 * proportion of the article that has been scrolled. The "scrollMaximum" is the highest
 * scroll percentage reached so far during the current page view.
 *
 * ⚠️ **Note:** For accurate tracking, ensure that the main scrollable content
 * is wrapped in an element with "id="articlebody"". If this element is missing,
 * the measurements will be based on the entire page height, which may lead to less precise results.
 *
 * @returns An object containing:
 * - "scrollPercent" — The current scroll position as a number between "0" and "1".
 * - "scrollMaximum" — The maximum scroll percentage reached so far.
 *
 * @example
 * const { scrollPercent, scrollMaximum } = scrollReport();
 * console.log("Current: ${scrollPercent}, Max: ${scrollMaximum}");
 */
declare function scrollReport(): {
    scrollPercent: number;
    scrollMaximum: number;
};
/**
 * Initializes automatic scroll tracking on the page by adding an window event listener called "scroll". Invokes scrollReport() to determine scrollPercent and scrollMaximum.
 *
 * @param callback - Function called whenever the scroll percentage changes.
 *                   Receives the current scroll percentage, maximum reached,
 *                   and the previous scroll percentage.
 * @returns A cleanup function that removes the scroll listener.
 *
 * @example
 * const stopTracking = initScrollTracking(({ scrollPercent, scrollMaximum, previousPercent }) => {
 *   console.log(scrollPercent, scrollMaximum, previousPercent);
 * });
 *
 * // Later, to stop tracking:
 * stopTracking();
 */
declare function initScrollTracking(callback: (data: {
    scrollPercent: number;
    scrollMaximum: number;
    previousPercent: number | null;
}) => void): () => void;

export { initScrollTracking, scrollReport };