Scroll Position Tracker

Build a scroll position tracker that monitors and reports the real-time position of a scrollable element. The tracker should capture position data during scroll animations with high precision and provide detailed scroll analytics.

@generates

Requirements

Position Monitoring

Create a tracker that continuously monitors the scroll position of an element during user interactions. The tracker should capture position updates in real-time during scroll animations, not just at the start and end of scrolling.

Position Data Collection

The tracker must collect the following information for each position update:

• Current X coordinate
• Current Y coordinate
• Timestamp of the position capture
• Whether the scroll animation is currently active

Analytics

The tracker should provide analytics about the scroll session:

• Total distance scrolled (absolute value of position changes)
• Number of position updates captured
• Average update frequency (updates per second)
• Scroll duration (time between first and last update)

API

/**
 * Configuration options for the scroll tracker
 */
export interface TrackerConfig {
  wrapper: string | HTMLElement;
  onUpdate?: (data: PositionData) => void;
}

/**
 * Position data captured during scrolling
 */
export interface PositionData {
  x: number;
  y: number;
  timestamp: number;
  isScrolling: boolean;
}

/**
 * Analytics data for a scroll session
 */
export interface ScrollAnalytics {
  totalDistance: number;
  updateCount: number;
  averageFrequency: number;
  duration: number;
}

/**
 * ScrollTracker class for monitoring scroll position
 */
export class ScrollTracker {
  constructor(config: TrackerConfig);

  /**
   * Get the current position
   */
  getCurrentPosition(): PositionData;

  /**
   * Get analytics for the current session
   */
  getAnalytics(): ScrollAnalytics;

  /**
   * Clear all collected position data
   */
  reset(): void;

  /**
   * Clean up resources
   */
  destroy(): void;
}

Test Cases

Basic Position Tracking

• When a scroll occurs, the tracker captures multiple position updates during the animation @test
• The position data includes x, y coordinates and a timestamp @test

Real-time Updates

• Position updates are captured more than once during a single scroll animation @test
• The update callback is called with current position data during scrolling @test

Analytics

• Total distance calculation sums absolute position changes @test
• Update count reflects the number of position captures @test

Dependencies { .dependencies }

better-scroll { .dependency }

Provides smooth momentum-based scrolling with real-time position tracking capabilities. @satisfied-by