Scroll Event Tracker

Build a module that monitors and tracks scroll lifecycle events in a scrollable container, providing detailed analytics about user scrolling behavior.

Capabilities

Event Tracking

Tracks all phases of the scrolling lifecycle and records them in chronological order.

• Records when the user first touches or clicks in the scroll area before actual scrolling begins @test
• Records when scrolling motion actually starts (after movement threshold is crossed) @test
• Records continuous scroll position updates during active scrolling @test
• Records when the scroll animation completes and comes to rest @test

Event Data Collection

Captures relevant information for each scroll event.

• Stores the event type for each recorded event @test
• Stores timestamp for each event occurrence @test
• Stores scroll position (x, y coordinates) for scroll events @test

Analytics Interface

Provides methods to query and analyze the tracked events.

• Returns an array of all tracked events in chronological order @test
• Returns count of how many times each event type occurred @test
• Clears all tracked events when requested @test

Implementation

@generates

API

interface ScrollEvent {
  type: 'beforeScrollStart' | 'scrollStart' | 'scroll' | 'scrollEnd';
  timestamp: number;
  position?: { x: number; y: number };
}

export class ScrollTracker {
  /**
   * Initializes the scroll tracker with a scrollable element.
   * Sets up event listeners to track all scroll lifecycle events.
   *
   * @param element - The DOM element to attach the scroller to
   */
  constructor(element: HTMLElement);

  /**
   * Returns all tracked scroll events in chronological order.
   *
   * @returns Array of scroll events
   */
  getEvents(): ScrollEvent[];

  /**
   * Returns the count of occurrences for each event type.
   *
   * @returns Object with event types as keys and counts as values
   */
  getEventCounts(): Record<string, number>;

  /**
   * Clears all tracked events from memory.
   */
  clearEvents(): void;

  /**
   * Cleanup method to remove event listeners and destroy the scroller instance.
   */
  destroy(): void;
}

Dependencies { .dependencies }

better-scroll { .dependency }

A mobile-first scrolling library that provides smooth, momentum-based scrolling with comprehensive event lifecycle support including beforeScrollStart, scrollStart, scroll, and scrollEnd events.

@satisfied-by