mtrl-addons 0.1.2 → 0.2.2

package/src/core/list-manager/features/viewport/scrolling.ts

@@ -1,795 +0,0 @@
-/**
- * Scrolling Module - Virtual scrolling with integrated velocity tracking
- * Handles wheel events, scroll position management, scrollbar interactions, and velocity measurement
- */
-
-import type {
-  ListManagerComponent,
-  ItemRange,
-  SpeedTracker,
-} from "../../types";
-import { LIST_MANAGER_CONSTANTS } from "../../constants";
-import { clamp } from "../../utils/calculations";
-import type { ItemSizeManager } from "./item-size";
-
-/**
- * Configuration for scrolling functionality
- */
-export interface ScrollingConfig {
-  orientation: "vertical" | "horizontal";
-  enableScrollbar: boolean;
-  // Tracking configuration
-  trackingEnabled?: boolean;
-  measurementWindow?: number;
-  decelerationFactor?: number;
-  decayCheckInterval?: number;
-  fastThreshold?: number;
-  slowThreshold?: number;
-  smoothingFactor?: number;
-  // Callbacks
-  onScrollPositionChanged?: (data: {
-    position: number;
-    direction: "forward" | "backward";
-    previousPosition?: number;
-    targetIndex?: number;
-    alignment?: string;
-    source?: string;
-  }) => void;
-  onVirtualRangeChanged?: (range: ItemRange) => void;
-  onSpeedChanged?: (data: {
-    speed: number;
-    smoothedSpeed: number;
-    direction: "forward" | "backward";
-    isAccelerating: boolean;
-    acceleration: number;
-  }) => void;
-}
-
-/**
- * Scrolling state interface
- */
-export interface ScrollingState {
-  virtualScrollPosition: number;
-  totalVirtualSize: number;
-  containerSize: number;
-  thumbPosition: number;
-  scrollbarVisible: boolean;
-  scrollbarFadeTimeout: number | null;
-}
-
-/**
- * Scrolling manager interface with integrated tracking
- */
-export interface ScrollingManager {
-  // Core scrolling
-  handleWheel(event: WheelEvent): void;
-  scrollToPosition(position: number, source?: string): void;
-  scrollToIndex(index: number, alignment?: "start" | "center" | "end"): void;
-
-  // Container positioning
-  updateContainerPosition(): void;
-
-  // Scrollbar management
-  updateScrollbar(): void;
-  showScrollbar(): void;
-  setupScrollbar(): void;
-  destroyScrollbar(): void;
-
-  // Wheel event management
-  setupWheelEvents(): void;
-  removeWheelEvents(): void;
-
-  // State
-  getScrollPosition(): number;
-  getContainerSize(): number;
-  getTotalVirtualSize(): number;
-  updateState(updates: Partial<ScrollingState>): void;
-
-  // Integrated tracking API
-  getCurrentSpeed(): number;
-  getDirection(): "forward" | "backward";
-  getAcceleration(): number;
-  isAccelerating(): boolean;
-  getSpeedHistory(): number[];
-  getSmoothedSpeed(): number;
-  getAverageSpeed(): number;
-  isFastScrolling(): boolean;
-  isSlowScrolling(): boolean;
-  isMediumScrolling(): boolean;
-  updateSpeedThresholds(fast: number, slow: number): void;
-  resetTracking(): void;
-  getTracker(): SpeedTracker;
-  isTrackingEnabled(): boolean;
-}
-
-/**
- * Creates a scrolling manager for virtual scroll position and scrollbar management
- */
-export const createScrollingManager = (
-  component: ListManagerComponent,
-  itemSizeManager: ItemSizeManager,
-  config: ScrollingConfig,
-  calculateVisibleRange: () => ItemRange,
-  renderItems: () => void,
-  getTotalItems?: () => number,
-  loadDataForRange?: (range: { start: number; end: number }) => void, // Change to loadDataForRange callback
-  getHeightCapInfo?: () => any, // Get height cap info from virtual manager
-  calculateVirtualPositionForIndex?: (index: number) => number // Calculate virtual position for index
-): ScrollingManager => {
-  const {
-    orientation,
-    enableScrollbar,
-    trackingEnabled = true,
-    measurementWindow = LIST_MANAGER_CONSTANTS.SPEED_TRACKING
-      .MEASUREMENT_WINDOW,
-    decelerationFactor = 0.9,
-    smoothingFactor = 0.8,
-    decayCheckInterval = 50, // Check decay every 50ms instead of every frame
-    onScrollPositionChanged,
-    onVirtualRangeChanged,
-    onSpeedChanged,
-  } = config;
-
-  let fastThreshold =
-    config.fastThreshold ||
-    LIST_MANAGER_CONSTANTS.SPEED_TRACKING.FAST_SCROLL_THRESHOLD;
-  let slowThreshold =
-    config.slowThreshold ||
-    LIST_MANAGER_CONSTANTS.SPEED_TRACKING.SLOW_SCROLL_THRESHOLD;
-
-  // Scrolling state
-  let virtualScrollPosition = 0;
-  let totalVirtualSize = 0;
-  let containerSize = 0;
-  let thumbPosition = 0;
-  let scrollbarVisible = false;
-  let scrollbarFadeTimeout: number | null = null;
-
-  // Direct scrolling - no animation for immediate response
-
-  // Velocity tracking state
-  let speedTracker: SpeedTracker = {
-    velocity: 0,
-    direction: "forward",
-    isAccelerating: false,
-    lastMeasurement: Date.now(),
-  };
-
-  let speedHistory: number[] = [];
-  let positionHistory: { position: number; timestamp: number }[] = [];
-  let smoothedSpeed = 0;
-  let lastPosition = 0;
-  let lastTimestamp = Date.now();
-  let currentAcceleration = 0;
-  let lastIdleCheckPosition = 0;
-  let idleCheckFrame: number | null = null;
-
-  // Scrollbar state (managed by external plugin)
-  let scrollbarPlugin: any = null;
-
-  // Items container reference
-  let itemsContainer: HTMLElement | null = null;
-
-  // Track last render time to avoid excessive rendering
-  let lastRenderTime = 0;
-
-  /**
-   * Initialize scrolling with container reference
-   */
-  const setItemsContainer = (container: HTMLElement) => {
-    itemsContainer = container;
-  };
-
-  /**
-   * Initialize velocity tracking
-   */
-  const initializeTracking = (): void => {
-    if (!trackingEnabled) return;
-    startIdleDetection();
-  };
-
-  /**
-   * Start idle detection
-   */
-  const startIdleDetection = (): void => {
-    const checkIdle = () => {
-      if (!trackingEnabled) {
-        idleCheckFrame = null;
-        return;
-      }
-
-      // Check if position hasn't changed and velocity is not already 0
-      if (
-        virtualScrollPosition === lastIdleCheckPosition &&
-        speedTracker.velocity > 0
-      ) {
-        setVelocityToZero();
-      }
-
-      lastIdleCheckPosition = virtualScrollPosition;
-      idleCheckFrame = requestAnimationFrame(checkIdle);
-    };
-
-    idleCheckFrame = requestAnimationFrame(checkIdle);
-  };
-
-  /**
-   * Set velocity to zero and trigger necessary updates
-   */
-  const setVelocityToZero = (): void => {
-    // Reset velocity state
-    speedTracker.velocity = 0;
-    speedTracker.isAccelerating = false;
-    smoothedSpeed = 0;
-    currentAcceleration = 0;
-
-    // Emit speed change
-    onSpeedChanged?.({
-      speed: 0,
-      smoothedSpeed: 0,
-      direction: speedTracker.direction,
-      isAccelerating: false,
-      acceleration: 0,
-    });
-
-    component.emit?.("speed:changed", {
-      speed: 0,
-      direction: speedTracker.direction,
-      isAccelerating: false,
-    });
-
-    // Trigger rendering and data loading
-    renderItems();
-    const visibleRange = calculateVisibleRange();
-    if (loadDataForRange) {
-      loadDataForRange({
-        start: visibleRange.start,
-        end: visibleRange.end,
-      });
-    }
-  };
-
-  /**
-   * Update velocity tracking
-   */
-  const updateVelocityTracking = (
-    deltaPosition: number,
-    deltaTime: number,
-    lastPosition: number
-  ): void => {
-    if (!trackingEnabled) return;
-
-    const now = Date.now();
-    const position = lastPosition + deltaPosition;
-
-    // If delta is 0 or very small, set velocity to 0
-    if (Math.abs(deltaPosition) < 0.1) {
-      if (speedTracker.velocity > 0) {
-        setVelocityToZero();
-      }
-      return;
-    }
-
-    // Calculate instantaneous velocity
-    const instantVelocity = Math.abs(deltaPosition) / deltaTime;
-
-    // Update direction
-    const newDirection = deltaPosition >= 0 ? "forward" : "backward";
-
-    // Calculate acceleration
-    const previousVelocity = speedTracker.velocity;
-    currentAcceleration = (instantVelocity - previousVelocity) / deltaTime;
-
-    // Update speed tracker
-    speedTracker = {
-      velocity: instantVelocity,
-      direction: newDirection,
-      isAccelerating: currentAcceleration > 0,
-      lastMeasurement: now,
-    };
-
-    // Add to position history for windowed calculations
-    positionHistory.push({ position, timestamp: now });
-
-    // Clean old history outside measurement window
-    const windowStart = now - measurementWindow;
-    positionHistory = positionHistory.filter(
-      (entry) => entry.timestamp >= windowStart
-    );
-
-    // Calculate windowed velocity if we have enough data
-    if (positionHistory.length >= 2) {
-      const windowedVelocity = calculateWindowedVelocity();
-      speedTracker.velocity = windowedVelocity;
-    }
-
-    // Update speed history
-    speedHistory.push(speedTracker.velocity);
-    if (speedHistory.length > 20) {
-      speedHistory.shift();
-    }
-
-    // Update smoothed speed using exponential smoothing
-    smoothedSpeed =
-      smoothedSpeed * smoothingFactor +
-      speedTracker.velocity * (1 - smoothingFactor);
-
-    // Update state
-    lastPosition = position;
-    lastTimestamp = now;
-
-    // Emit speed changed event
-    onSpeedChanged?.({
-      speed: speedTracker.velocity,
-      smoothedSpeed,
-      direction: speedTracker.direction,
-      isAccelerating: speedTracker.isAccelerating,
-      acceleration: currentAcceleration,
-    });
-
-    component.emit?.("speed:changed", {
-      speed: speedTracker.velocity, // Use raw velocity for loading decisions
-      direction: speedTracker.direction,
-      isAccelerating: speedTracker.isAccelerating,
-    });
-  };
-
-  /**
-   * Calculate windowed velocity for better accuracy
-   */
-  const calculateWindowedVelocity = (): number => {
-    if (positionHistory.length < 2) return 0;
-
-    const latest = positionHistory[positionHistory.length - 1];
-    const earliest = positionHistory[0];
-
-    const totalDistance = Math.abs(latest.position - earliest.position);
-    const totalTime = latest.timestamp - earliest.timestamp;
-
-    return totalTime > 0 ? totalDistance / totalTime : 0;
-  };
-
-  /**
-   * Handle wheel events for scrolling
-   */
-  const handleWheel = (event: WheelEvent): void => {
-    event.preventDefault();
-
-    const now = Date.now();
-    const actualDeltaTime = Math.max(1, now - lastTimestamp); // Minimum 1ms to avoid division by zero
-    lastTimestamp = now;
-
-    const sensitivity =
-      LIST_MANAGER_CONSTANTS.VIRTUAL_SCROLL.SCROLL_SENSITIVITY;
-    const delta = orientation === "vertical" ? event.deltaY : event.deltaX;
-
-    // Direct scroll delta for immediate response
-    let scrollDelta = delta * sensitivity;
-
-    const previousPosition = virtualScrollPosition;
-    const maxScroll = Math.max(0, totalVirtualSize - containerSize);
-
-    // Check if we're using compressed virtual space
-    const actualTotalItems = getTotalItems
-      ? getTotalItems()
-      : component.totalItems;
-    const itemSize = itemSizeManager.getEstimatedItemSize();
-    const actualTotalSize = actualTotalItems * itemSize;
-    const isCompressed = actualTotalSize > totalVirtualSize;
-
-    // Special handling when using compressed space and near boundaries
-    if (isCompressed) {
-      const isNearBottom = virtualScrollPosition >= maxScroll - 100;
-      const isNearTop = virtualScrollPosition <= 100;
-
-      if (isNearBottom || isNearTop) {
-        // We're using compressed virtual space
-        const compressionRatio = totalVirtualSize / actualTotalSize;
-
-        // Reduce scroll delta to account for compression
-        // This ensures we don't skip ranges when scrolling
-        scrollDelta = scrollDelta * compressionRatio;
-
-        // Further reduce delta when very close to boundaries
-        if ((isNearBottom && delta > 0) || (isNearTop && delta < 0)) {
-          scrollDelta = scrollDelta * 0.5; // Half speed at boundaries
-        }
-      }
-    }
-
-    let newPosition = virtualScrollPosition + scrollDelta;
-
-    // Apply boundary clamping
-    newPosition = clamp(newPosition, 0, maxScroll);
-
-    // Ensure we can reach the very end with mouse wheel
-    if (newPosition > maxScroll - 10 && delta > 0) {
-      // Close to the end and scrolling down, snap to max
-      newPosition = maxScroll;
-    }
-
-    // Update scroll position immediately for instant feedback
-    virtualScrollPosition = newPosition;
-
-    // Update velocity tracking with the actual delta and real time
-    const deltaPosition = newPosition - previousPosition;
-    updateVelocityTracking(deltaPosition, actualDeltaTime, previousPosition);
-
-    // Update container position immediately for instant feedback
-    updateContainerPosition();
-    updateScrollbar();
-    showScrollbar();
-
-    // Trigger rendering for new visible range
-    renderItems();
-
-    // Emit events
-    const direction = newPosition > previousPosition ? "forward" : "backward";
-    onScrollPositionChanged?.({
-      position: virtualScrollPosition,
-      direction,
-      previousPosition,
-    });
-
-    const newVisibleRange = calculateVisibleRange();
-    onVirtualRangeChanged?.(newVisibleRange);
-  };
-
-  /**
-   * Scroll to specific index
-   */
-  const scrollToIndex = (
-    index: number,
-    alignment: "start" | "center" | "end" = "start"
-  ): void => {
-    // Use getTotalItems callback if available, otherwise fall back to component.totalItems
-    const totalItems = getTotalItems ? getTotalItems() : component.totalItems;
-
-    if (index < 0 || index >= totalItems) {
-      return;
-    }
-
-    const previousPosition = virtualScrollPosition;
-    let targetPosition = 0;
-
-    // Calculate position based on measured sizes
-    for (let i = 0; i < index; i++) {
-      targetPosition +=
-        itemSizeManager.getMeasuredSize(i) ||
-        itemSizeManager.getEstimatedItemSize();
-    }
-
-    // Adjust position based on alignment
-    switch (alignment) {
-      case "center":
-        targetPosition -= containerSize / 2;
-        break;
-      case "end":
-        targetPosition -= containerSize;
-        break;
-      // 'start' is default - no adjustment needed
-    }
-
-    // Use virtual manager's position calculator for index-based scrolling
-    if (calculateVirtualPositionForIndex) {
-      const virtualPosition = calculateVirtualPositionForIndex(index);
-
-      // Only use virtual position if it differs from calculated position
-      if (Math.abs(virtualPosition - targetPosition) > 1) {
-        targetPosition = virtualPosition;
-
-        // Adjust for alignment after mapping to virtual space
-        switch (alignment) {
-          case "center":
-            targetPosition -= containerSize / 2;
-            break;
-          case "end":
-            targetPosition -= containerSize;
-            break;
-        }
-      }
-    }
-
-    // Ensure position is within bounds
-    const maxPosition = Math.max(0, totalVirtualSize - containerSize);
-    targetPosition = Math.max(0, Math.min(targetPosition, maxPosition));
-
-    // Update scroll position immediately
-    virtualScrollPosition = targetPosition;
-
-    // Update UI immediately
-    updateContainerPosition();
-    updateScrollbar();
-    showScrollbar();
-
-    // Calculate new visible range and notify
-    const newVisibleRange = calculateVisibleRange();
-
-    // Notify about scroll position change
-    onScrollPositionChanged?.({
-      position: virtualScrollPosition,
-      previousPosition,
-      direction: targetPosition > previousPosition ? "forward" : "backward",
-    });
-
-    // Notify about virtual range change
-    onVirtualRangeChanged?.(newVisibleRange);
-
-    // Trigger rendering for the new range
-    renderItems();
-
-    // Load data for the new range if needed
-    if (loadDataForRange) {
-      loadDataForRange({
-        start: newVisibleRange.start,
-        end: newVisibleRange.end,
-      });
-    }
-  };
-
-  /**
-   * Scroll to a specific position
-   */
-  const scrollToPosition = (position: number, source?: string): void => {
-    const maxScroll = Math.max(0, totalVirtualSize - containerSize);
-    const clampedPosition = clamp(position, 0, maxScroll);
-
-    if (clampedPosition === virtualScrollPosition) {
-      return;
-    }
-
-    const previousPosition = virtualScrollPosition;
-
-    // Update scroll position immediately
-    virtualScrollPosition = clampedPosition;
-
-    // Update velocity tracking with actual time delta
-    const now = Date.now();
-    const actualDeltaTime = Math.max(1, now - lastTimestamp);
-    const deltaPosition = clampedPosition - previousPosition;
-
-    // For scrollbar dragging, use actual time between updates
-    if (source === "scrollbar-drag") {
-      updateVelocityTracking(deltaPosition, actualDeltaTime, previousPosition);
-    } else {
-      // For other sources, use default frame time
-      updateVelocityTracking(deltaPosition, 16, previousPosition);
-    }
-
-    lastTimestamp = now;
-
-    // Update UI immediately
-    updateContainerPosition();
-    updateScrollbar();
-    showScrollbar();
-
-    // Trigger rendering immediately for all sources
-    renderItems();
-
-    // For scrollbar drag, also ensure we load data
-    if (source === "scrollbar-drag") {
-      const visibleRange = calculateVisibleRange();
-      if (loadDataForRange) {
-        loadDataForRange({
-          start: visibleRange.start,
-          end: visibleRange.end,
-        });
-      }
-    }
-
-    // Emit events
-    const direction =
-      clampedPosition > previousPosition ? "forward" : "backward";
-    onScrollPositionChanged?.({
-      position: virtualScrollPosition,
-      direction,
-      previousPosition,
-    });
-
-    const newVisibleRange = calculateVisibleRange();
-    onVirtualRangeChanged?.(newVisibleRange);
-  };
-
-  /**
-   * Update container position for virtual scrolling with element accumulation
-   */
-  const updateContainerPosition = (): void => {
-    if (!itemsContainer) return;
-
-    // Don't apply transform to container - rely on absolute positioning of items
-    // Just trigger item position updates
-    if ((component as any).viewport?.updateItemPositions) {
-      (component as any).viewport.updateItemPositions();
-    }
-  };
-
-  /**
-   * Update scrollbar thumb position and size (delegated to external plugin)
-   */
-  const updateScrollbar = (): void => {
-    if (!enableScrollbar || !scrollbarPlugin) return;
-
-    // Calculate scroll ratio for external scrollbar plugin
-    const scrollRatio =
-      totalVirtualSize > containerSize
-        ? virtualScrollPosition / (totalVirtualSize - containerSize)
-        : 0;
-
-    // Update external scrollbar plugin
-    if (scrollbarPlugin.updateScrollPosition) {
-      scrollbarPlugin.updateScrollPosition(virtualScrollPosition);
-    }
-  };
-
-  /**
-   * Setup scrollbar (delegated to external plugin)
-   */
-  const setupScrollbar = (): void => {
-    // Scrollbar setup is handled by external plugin
-    // This method is kept for API compatibility
-  };
-
-  /**
-   * Setup scrollbar events (delegated to external plugin)
-   */
-  const setupScrollbarEvents = (): void => {
-    // Scrollbar events are handled by external plugin
-    // This method is kept for API compatibility
-  };
-
-  /**
-   * Show scrollbar (delegated to external plugin)
-   */
-  const showScrollbar = (): void => {
-    if (!enableScrollbar || !scrollbarPlugin) return;
-
-    // Show scrollbar through external plugin
-    if (scrollbarPlugin.showScrollbar) {
-      scrollbarPlugin.showScrollbar();
-    }
-  };
-
-  /**
-   * Cleanup
-   */
-  const destroy = (): void => {
-    destroyScrollbar();
-    if (idleCheckFrame) {
-      cancelAnimationFrame(idleCheckFrame);
-      idleCheckFrame = null;
-    }
-  };
-
-  /**
-   * Destroy scrollbar (delegated to external plugin)
-   */
-  const destroyScrollbar = (): void => {
-    if (scrollbarPlugin && scrollbarPlugin.destroy) {
-      scrollbarPlugin.destroy();
-    }
-    scrollbarPlugin = null;
-
-    if (scrollbarFadeTimeout) {
-      clearTimeout(scrollbarFadeTimeout);
-      scrollbarFadeTimeout = null;
-    }
-  };
-
-  /**
-   * Get current scroll position
-   */
-  const getScrollPosition = (): number => virtualScrollPosition;
-
-  /**
-   * Get container size
-   */
-  const getContainerSize = (): number => containerSize;
-
-  /**
-   * Get total virtual size
-   */
-  const getTotalVirtualSize = (): number => totalVirtualSize;
-
-  /**
-   * Update scrolling state
-   */
-  const updateState = (updates: Partial<ScrollingState>): void => {
-    if (updates.virtualScrollPosition !== undefined) {
-      virtualScrollPosition = updates.virtualScrollPosition;
-    }
-    if (updates.totalVirtualSize !== undefined) {
-      totalVirtualSize = updates.totalVirtualSize;
-    }
-    if (updates.containerSize !== undefined) {
-      containerSize = updates.containerSize;
-    }
-    if (updates.thumbPosition !== undefined) {
-      thumbPosition = updates.thumbPosition;
-    }
-    if (updates.scrollbarVisible !== undefined) {
-      scrollbarVisible = updates.scrollbarVisible;
-    }
-    if (updates.scrollbarFadeTimeout !== undefined) {
-      scrollbarFadeTimeout = updates.scrollbarFadeTimeout;
-    }
-  };
-
-  // Initialize tracking
-  initializeTracking();
-
-  return {
-    // Core scrolling
-    handleWheel,
-    scrollToIndex,
-    scrollToPosition,
-
-    // Container positioning
-    updateContainerPosition,
-
-    // Scrollbar management
-    updateScrollbar,
-    showScrollbar,
-    setupScrollbar,
-    destroyScrollbar: destroy,
-
-    // Wheel event management
-    setupWheelEvents: () => {
-      component.element.addEventListener("wheel", handleWheel, {
-        passive: false,
-      });
-    },
-    removeWheelEvents: () => {
-      component.element.removeEventListener("wheel", handleWheel);
-    },
-
-    // State
-    getScrollPosition,
-    getContainerSize,
-    getTotalVirtualSize,
-    updateState,
-
-    // Integrated tracking API
-    getCurrentSpeed: () => speedTracker.velocity,
-    getDirection: () => speedTracker.direction,
-    getAcceleration: () => currentAcceleration,
-    isAccelerating: () => speedTracker.isAccelerating,
-    getSpeedHistory: () => [...speedHistory],
-    getSmoothedSpeed: () => smoothedSpeed,
-    getAverageSpeed: () => {
-      if (speedHistory.length === 0) return 0;
-      return speedHistory.reduce((sum, v) => sum + v, 0) / speedHistory.length;
-    },
-    isFastScrolling: () => smoothedSpeed > fastThreshold,
-    isSlowScrolling: () => smoothedSpeed < slowThreshold,
-    isMediumScrolling: () =>
-      smoothedSpeed >= slowThreshold && smoothedSpeed <= fastThreshold,
-    updateSpeedThresholds: (fast: number, slow: number) => {
-      fastThreshold = fast;
-      slowThreshold = slow;
-    },
-    resetTracking: () => {
-      speedTracker = {
-        velocity: 0,
-        direction: "forward",
-        isAccelerating: false,
-        lastMeasurement: Date.now(),
-      };
-      speedHistory = [];
-      positionHistory = [];
-      smoothedSpeed = 0;
-      lastPosition = 0;
-      lastTimestamp = Date.now();
-      currentAcceleration = 0;
-    },
-    getTracker: () => ({ ...speedTracker }),
-    isTrackingEnabled: () => trackingEnabled,
-
-    // Internal (for viewport setup)
-    setItemsContainer,
-    setScrollbarPlugin: (plugin: any) => {
-      scrollbarPlugin = plugin;
-    },
-  } as ScrollingManager & {
-    setItemsContainer: (container: HTMLElement) => void;
-  };
-};