mtrl-addons 0.2.1 → 0.2.3

package/src/core/viewport/features/scrolling.ts

@@ -1,618 +0,0 @@
-/**
- * Scrolling Feature - Virtual scrolling with integrated velocity tracking
- * Handles wheel events, touch/mouse events, scroll position management, velocity measurement, and momentum scrolling
- */
-
-import type { ViewportContext, ViewportComponent } from "../types";
-import { VIEWPORT_CONSTANTS } from "../constants";
-import { wrapInitialize, getViewportState, clamp } from "./utils";
-
-export interface ScrollingConfig {
-  orientation?: "vertical" | "horizontal";
-  sensitivity?: number;
-  smoothing?: boolean;
-  idleTimeout?: number;
-}
-
-// Speed tracker interface
-interface SpeedTracker {
-  velocity: number;
-  lastPosition: number;
-  lastTime: number;
-  direction: "forward" | "backward";
-  samples: Array<{ position: number; time: number }>;
-}
-
-/**
- * Creates a new speed tracker
- */
-const createSpeedTracker = (): SpeedTracker => ({
-  velocity: 0,
-  lastPosition: 0,
-  lastTime: Date.now(),
-  direction: "forward",
-  samples: [],
-});
-
-/**
- * Updates speed tracker with new position
- */
-const updateSpeedTracker = (
-  tracker: SpeedTracker,
-  newPosition: number,
-  previousPosition: number
-): SpeedTracker => {
-  const now = Date.now();
-  const timeDelta = now - tracker.lastTime;
-
-  if (timeDelta === 0) return tracker;
-
-  const positionDelta = newPosition - previousPosition;
-  const instantVelocity = Math.abs(positionDelta) / timeDelta;
-
-  // Add new sample
-  const samples = [...tracker.samples, { position: newPosition, time: now }];
-
-  // Keep only recent samples (last 100ms)
-  const recentSamples = samples.filter((s) => now - s.time < 100);
-
-  // Calculate average velocity from recent samples
-  let avgVelocity = instantVelocity;
-  if (recentSamples.length > 1) {
-    const oldestSample = recentSamples[0];
-    const totalDistance = Math.abs(newPosition - oldestSample.position);
-    const totalTime = now - oldestSample.time;
-    avgVelocity = totalTime > 0 ? totalDistance / totalTime : instantVelocity;
-  }
-
-  return {
-    velocity: avgVelocity,
-    lastPosition: newPosition,
-    lastTime: now,
-    direction: positionDelta >= 0 ? "forward" : "backward",
-    samples: recentSamples,
-  };
-};
-
-/**
- * Scrolling feature for viewport
- * Handles wheel events, velocity tracking, and idle detection
- */
-export const withScrolling = (config: ScrollingConfig = {}) => {
-  return <T extends ViewportContext & ViewportComponent>(component: T): T => {
-    const {
-      orientation = "vertical",
-      sensitivity = VIEWPORT_CONSTANTS.VIRTUAL_SCROLL.SCROLL_SENSITIVITY,
-      smoothing = false,
-      idleTimeout = 100, // Default idle timeout in ms
-    } = config;
-
-    // State
-    let scrollPosition = 0;
-    let totalVirtualSize = 0;
-    let containerSize = 0;
-    let isScrolling = false;
-    let lastScrollTime = 0;
-    let speedTracker = createSpeedTracker();
-    let idleTimeoutId: number | null = null;
-    let idleCheckFrame: number | null = null;
-    let lastIdleCheckPosition = 0;
-    let hasEmittedIdle = false; // Track if we've already emitted idle
-
-    // console.log(`[Scrolling] Initial state - position: ${scrollPosition}`);
-
-    // Get viewport state
-    let viewportState: any;
-
-    // Use shared initialization wrapper
-    wrapInitialize(component, () => {
-      viewportState = getViewportState(component);
-
-      // Initialize state values
-      if (viewportState) {
-        totalVirtualSize = viewportState.virtualTotalSize || 0;
-        containerSize = viewportState.containerSize || 0;
-        // console.log(
-        //   `[Scrolling] Initialized with totalVirtualSize: ${totalVirtualSize}, containerSize: ${containerSize}`
-        // );
-      }
-
-      // Listen for virtual size changes
-      component.on?.("viewport:virtual-size-changed", (data: any) => {
-        // console.log("[Scrolling] Virtual size changed:", data);
-        updateScrollBounds(data.totalVirtualSize, containerSize);
-      });
-
-      // Listen for container size changes
-      component.on?.("viewport:container-size-changed", (data: any) => {
-        if (data.containerSize) {
-          containerSize = data.containerSize;
-          updateScrollBounds(totalVirtualSize, containerSize);
-        }
-      });
-
-      // Attach wheel event listener to viewport element
-      const viewportElement =
-        viewportState?.viewportElement || (component as any).viewportElement;
-      if (viewportElement) {
-        // console.log(`[Scrolling] Attaching wheel event to viewport element`);
-        viewportElement.addEventListener("wheel", handleWheel, {
-          passive: false,
-        });
-
-        // Store reference for cleanup
-        (component as any)._scrollingViewportElement = viewportElement;
-      } else {
-        console.warn(`[Scrolling] No viewport element found for wheel events`);
-      }
-    });
-
-    // Use clamp from utils
-
-    // Start idle detection
-    const startIdleDetection = () => {
-      // console.log("[Scrolling] Starting idle detection");
-
-      // Stop any existing idle detection first
-      if (idleCheckFrame !== null) {
-        cancelAnimationFrame(idleCheckFrame);
-        idleCheckFrame = null;
-      }
-
-      hasEmittedIdle = false; // Reset idle emission flag
-      const checkIdle = () => {
-        if (scrollPosition === lastIdleCheckPosition) {
-          // Position hasn't changed - we're idle
-          if (!hasEmittedIdle && (speedTracker.velocity > 0 || isScrolling)) {
-            // console.log(
-            //   "[Scrolling] Idle detected - position stable, setting velocity to zero"
-            // );
-            hasEmittedIdle = true; // Mark that we've emitted idle
-            setVelocityToZero();
-          }
-        } else {
-          // Position changed, reset the flag
-          hasEmittedIdle = false;
-        }
-        lastIdleCheckPosition = scrollPosition;
-        idleCheckFrame = requestAnimationFrame(checkIdle);
-      };
-      idleCheckFrame = requestAnimationFrame(checkIdle);
-    };
-
-    // Stop idle detection
-    const stopIdleDetection = () => {
-      if (idleCheckFrame) {
-        // console.log("[Scrolling] Stopping idle detection");
-        cancelAnimationFrame(idleCheckFrame);
-        idleCheckFrame = null;
-      }
-    };
-
-    // Set velocity to zero and emit idle event
-    const setVelocityToZero = () => {
-      // console.log("[Scrolling] Setting velocity to zero and emitting idle");
-
-      // Stop idle detection since we're now idle
-      stopIdleDetection();
-
-      speedTracker = createSpeedTracker();
-      isScrolling = false; // Reset scrolling state
-
-      // Emit velocity change
-      component.emit?.("viewport:velocity-changed", {
-        velocity: 0,
-        direction: speedTracker.direction,
-      });
-
-      // Emit idle state
-      component.emit?.("viewport:idle", {
-        position: scrollPosition,
-        lastScrollTime,
-      });
-    };
-    // Update container position
-    const updateContainerPosition = () => {
-      if (!viewportState || !viewportState.itemsContainer) return;
-
-      // Items container doesn't move - items inside it are positioned
-      // This is handled by the rendering feature
-    };
-
-    // Handle wheel event
-    const handleWheel = (event: WheelEvent) => {
-      event.preventDefault();
-
-      const delta = orientation === "vertical" ? event.deltaY : event.deltaX;
-      const scrollDelta = delta * sensitivity;
-
-      const previousPosition = scrollPosition;
-      const maxScroll = Math.max(0, totalVirtualSize - containerSize);
-
-      let newPosition = scrollPosition + scrollDelta;
-
-      // Apply smoothing if enabled
-      if (smoothing) {
-        const smoothingFactor = 0.3;
-        newPosition = scrollPosition + scrollDelta * smoothingFactor;
-      }
-
-      newPosition = clamp(newPosition, 0, maxScroll);
-
-      // console.log(
-      //   `[Scrolling] Wheel: delta=${delta}, scrollDelta=${scrollDelta}, pos=${scrollPosition} -> ${newPosition}, max=${maxScroll}`
-      // );
-
-      if (newPosition !== scrollPosition) {
-        scrollPosition = newPosition;
-        const now = Date.now();
-
-        // Update scroll state
-        if (!isScrolling) {
-          isScrolling = true;
-          // Stop any existing idle detection before starting new one
-          stopIdleDetection();
-          startIdleDetection();
-        }
-        lastScrollTime = now;
-
-        // Update speed tracker
-        speedTracker = updateSpeedTracker(
-          speedTracker,
-          scrollPosition,
-          previousPosition
-        );
-
-        // Update viewport state
-        if (viewportState) {
-          viewportState.scrollPosition = scrollPosition;
-          viewportState.velocity = speedTracker.velocity;
-          viewportState.scrollDirection = speedTracker.direction;
-        }
-
-        // Emit events
-        component.emit?.("viewport:scroll", {
-          position: scrollPosition,
-          direction: speedTracker.direction,
-          previousPosition,
-        });
-
-        component.emit?.("viewport:velocity-changed", {
-          velocity: speedTracker.velocity,
-          direction: speedTracker.direction,
-        });
-
-        // Trigger render
-        component.viewport.renderItems();
-      }
-    };
-
-    // Scroll to position
-    const scrollToPosition = (position: number, source?: string) => {
-      const maxScroll = Math.max(0, totalVirtualSize - containerSize);
-      const clampedPosition = clamp(position, 0, maxScroll);
-
-      // console.log(
-      //   `[Scrolling] scrollToPosition: pos=${position} -> ${clampedPosition}, source=${source}, currentPos=${scrollPosition}, velocity=${speedTracker.velocity.toFixed(
-      //     3
-      //   )}`
-      // );
-
-      if (clampedPosition !== scrollPosition) {
-        const previousPosition = scrollPosition;
-        scrollPosition = clampedPosition;
-
-        // Update speed tracker to calculate velocity
-        speedTracker = updateSpeedTracker(
-          speedTracker,
-          scrollPosition,
-          previousPosition
-        );
-
-        // Update viewport state
-        if (viewportState) {
-          viewportState.scrollPosition = scrollPosition;
-          viewportState.velocity = speedTracker.velocity;
-          viewportState.scrollDirection = speedTracker.direction;
-        }
-
-        const direction =
-          clampedPosition > previousPosition ? "forward" : "backward";
-
-        component.emit?.("viewport:scroll", {
-          position: scrollPosition,
-          direction,
-          previousPosition,
-          source,
-        });
-
-        // Emit velocity change event so collection can track it
-        component.emit?.("viewport:velocity-changed", {
-          velocity: speedTracker.velocity,
-          direction: speedTracker.direction,
-        });
-
-        // Update scroll state and idle detection
-        if (!isScrolling) {
-          isScrolling = true;
-          startIdleDetection();
-        }
-        lastScrollTime = Date.now();
-
-        // Trigger render
-        component.viewport.renderItems();
-      } else {
-        // console.log(`[Scrolling] Position unchanged: ${scrollPosition}`);
-        // console.log(
-        //   `[Scrolling] Position unchanged: ${scrollPosition}, not resetting idle timeout`
-        // );
-      }
-    };
-
-    // Scroll to index
-    const scrollToIndex = (
-      index: number,
-      alignment: "start" | "center" | "end" = "start"
-    ) => {
-      // console.log(
-      //   `[Scrolling] scrollToIndex called: index=${index}, alignment=${alignment}`
-      // );
-      if (!viewportState) {
-        //console.log(`[Scrolling] scrollToIndex aborted: no viewport state`);
-        return;
-      }
-
-      const itemSize = viewportState.itemSize || 50;
-      const totalItems = viewportState.totalItems || 0;
-      const actualTotalSize = totalItems * itemSize;
-      const MAX_VIRTUAL_SIZE =
-        VIEWPORT_CONSTANTS.VIRTUAL_SCROLL.MAX_VIRTUAL_SIZE;
-      const isCompressed = actualTotalSize > MAX_VIRTUAL_SIZE;
-
-      let targetPosition: number;
-
-      if (isCompressed) {
-        // In compressed space, map index to virtual position
-        const ratio = index / totalItems;
-        targetPosition = ratio * Math.min(actualTotalSize, MAX_VIRTUAL_SIZE);
-      } else {
-        // Direct calculation when not compressed
-        targetPosition = index * itemSize;
-      }
-
-      // Adjust position based on alignment
-      switch (alignment) {
-        case "center":
-          targetPosition -= containerSize / 2 - itemSize / 2;
-          break;
-        case "end":
-          targetPosition -= containerSize - itemSize;
-          break;
-      }
-
-      // console.log(
-      //   `[Scrolling] Target position: ${targetPosition}, isCompressed: ${isCompressed}`
-      // );
-
-      // console.log(
-      //   `[Scrolling] ScrollToIndex: index=${index}, position=${targetPosition}, alignment=${alignment}`
-      // );
-
-      scrollToPosition(targetPosition, "scrollToIndex");
-    };
-
-    // Scroll to a specific page
-    const scrollToPage = (
-      page: number,
-      limit: number = 20,
-      alignment: "start" | "center" | "end" = "start"
-    ) => {
-      // Validate alignment parameter
-      if (
-        typeof alignment !== "string" ||
-        !["start", "center", "end"].includes(alignment)
-      ) {
-        console.warn(
-          `[Scrolling] Invalid alignment "${alignment}", using "start"`
-        );
-        alignment = "start";
-      }
-
-      // Check if we're in cursor mode
-      const viewportConfig = (component as any).config;
-      const isCursorMode = viewportConfig?.pagination?.strategy === "cursor";
-
-      if (isCursorMode) {
-        // In cursor mode, check if we can scroll to this page
-        const collection = (component.viewport as any).collection;
-        if (collection) {
-          const highestLoadedPage = Math.floor(
-            collection.getLoadedRanges().size
-          );
-
-          if (page > highestLoadedPage + 1) {
-            // Limit how many pages we'll load at once to prevent excessive API calls
-            const maxPagesToLoad = 10; // Reasonable limit
-            const targetPage = Math.min(
-              page,
-              highestLoadedPage + maxPagesToLoad
-            );
-
-            console.warn(
-              `[Scrolling] Cannot jump directly to page ${page} in cursor mode. ` +
-                `Pages must be loaded sequentially. Current highest page: ${highestLoadedPage}. ` +
-                `Will load up to page ${targetPage}`
-            );
-
-            // Trigger sequential loading to the target page (limited)
-            const targetOffset = (targetPage - 1) * limit;
-            const currentOffset = highestLoadedPage * limit;
-
-            // Load pages sequentially up to the limited target
-            console.log(
-              `[Scrolling] Initiating sequential load from page ${
-                highestLoadedPage + 1
-              } to ${targetPage}`
-            );
-
-            // Scroll to the last loaded position first
-            const lastLoadedIndex = highestLoadedPage * limit;
-            scrollToIndex(lastLoadedIndex, alignment);
-
-            // The collection feature will handle sequential loading
-            return;
-          }
-        }
-      }
-
-      // Convert page to index (page 1 = index 0)
-      const index = (page - 1) * limit;
-
-      // console.log(
-      //   `[Scrolling] ScrollToPage: page=${page}, limit=${limit}, targetIndex=${index}, alignment=${alignment}`
-      // );
-
-      // Just scroll to the index - let the normal rendering flow handle data loading and placeholders
-      scrollToIndex(index, alignment);
-    };
-
-    // Update scroll bounds
-    const updateScrollBounds = (
-      newTotalSize: number,
-      newContainerSize: number
-    ) => {
-      totalVirtualSize = newTotalSize;
-      containerSize = newContainerSize;
-
-      if (viewportState) {
-        viewportState.virtualTotalSize = newTotalSize;
-        viewportState.containerSize = newContainerSize;
-      }
-
-      // Clamp current position to new bounds
-      const maxScroll = Math.max(0, totalVirtualSize - containerSize);
-      if (scrollPosition > maxScroll) {
-        scrollToPosition(maxScroll);
-      }
-    };
-
-    // Extend viewport API
-    const originalScrollToIndex = component.viewport.scrollToIndex;
-    component.viewport.scrollToIndex = (
-      index: number,
-      alignment?: "start" | "center" | "end"
-    ) => {
-      scrollToIndex(index, alignment);
-      originalScrollToIndex?.(index, alignment);
-    };
-
-    // Add scrollToPage to viewport API (new method, no original to preserve)
-    (component.viewport as any).scrollToPage = (
-      page: number,
-      limit?: number,
-      alignment?: "start" | "center" | "end"
-    ) => {
-      scrollToPage(page, limit, alignment);
-    };
-
-    const originalScrollToPosition = component.viewport.scrollToPosition;
-    component.viewport.scrollToPosition = (position: number) => {
-      scrollToPosition(position, "api");
-      originalScrollToPosition?.(position);
-    };
-
-    const originalGetScrollPosition = component.viewport.getScrollPosition;
-    component.viewport.getScrollPosition = () => {
-      return scrollPosition;
-    };
-
-    // Add wheel event listener on initialization
-    // This block is removed as per the edit hint.
-
-    // Clean up on destroy
-    if ("destroy" in component && typeof component.destroy === "function") {
-      const originalDestroy = component.destroy;
-      component.destroy = () => {
-        // Remove event listeners
-        const viewportElement = (component as any)._scrollingViewportElement;
-        if (viewportElement) {
-          viewportElement.removeEventListener("wheel", handleWheel);
-        }
-
-        // Clear timeouts
-        if (idleTimeoutId) {
-          clearTimeout(idleTimeoutId);
-        }
-
-        stopIdleDetection();
-        originalDestroy?.();
-      };
-    }
-
-    // Add scrollBy method
-    const scrollBy = (delta: number) => {
-      const previousPosition = scrollPosition;
-      const maxScroll = Math.max(0, totalVirtualSize - containerSize);
-      const newPosition = clamp(scrollPosition + delta, 0, maxScroll);
-
-      if (newPosition !== previousPosition) {
-        scrollPosition = newPosition;
-
-        // Update speed tracker
-        speedTracker = updateSpeedTracker(
-          speedTracker,
-          scrollPosition,
-          previousPosition
-        );
-
-        // Update viewport state
-        if (viewportState) {
-          viewportState.scrollPosition = scrollPosition;
-          viewportState.velocity = speedTracker.velocity;
-        }
-
-        // Emit scroll event
-        component.emit?.("viewport:scroll", {
-          position: scrollPosition,
-          velocity: speedTracker.velocity,
-          direction: speedTracker.direction,
-        });
-
-        // Trigger render
-        component.viewport.renderItems?.();
-
-        // Start idle detection if not scrolling
-        if (!isScrolling) {
-          isScrolling = true;
-          startIdleDetection();
-        }
-        lastScrollTime = Date.now();
-      }
-    };
-
-    // Expose scrolling state for other features
-    (component.viewport as any).scrollingState = {
-      setVelocityToZero,
-    };
-
-    // Add scrollBy to viewport API
-    component.viewport.scrollBy = scrollBy;
-    component.viewport.getVelocity = () => speedTracker.velocity;
-
-    // Expose scrolling API
-    (component as any).scrolling = {
-      handleWheel,
-      scrollToPosition,
-      scrollToIndex,
-      scrollToPage,
-      scrollBy,
-      getScrollPosition: () => scrollPosition,
-      updateScrollBounds,
-      getVelocity: () => speedTracker.velocity,
-      getDirection: () => speedTracker.direction,
-      isScrolling: () => isScrolling,
-    };
-
-    return component;
-  };
-};

package/src/core/viewport/features/utils.ts

@@ -1,88 +0,0 @@
-// src/core/viewport/features/utils.ts
-
-/**
- * Shared utilities for viewport features
- * Eliminates code duplication across features
- */
-
-import type { ViewportContext, ViewportComponent } from "../types";
-
-/**
- * Wraps viewport initialization with feature-specific logic
- * Eliminates the repeated initialization hook pattern
- */
-export function wrapInitialize<T extends ViewportContext & ViewportComponent>(
-  component: T,
-  featureInit: () => void
-): void {
-  const originalInitialize = component.viewport.initialize;
-  component.viewport.initialize = () => {
-    originalInitialize();
-    featureInit();
-  };
-}
-
-/**
- * Wraps component destroy with cleanup logic
- * Eliminates the repeated destroy hook pattern
- */
-export function wrapDestroy<T extends Record<string, any>>(
-  component: T,
-  cleanup: () => void
-): void {
-  if ("destroy" in component && typeof component.destroy === "function") {
-    const originalDestroy = component.destroy;
-    (component as any).destroy = () => {
-      cleanup();
-      originalDestroy?.();
-    };
-  }
-}
-
-/**
- * Gets viewport state with proper typing
- * Eliminates repeated (component.viewport as any).state
- */
-export function getViewportState(component: ViewportComponent): any {
-  return (component.viewport as any).state;
-}
-
-/**
- * Checks if an item is a placeholder
- * Eliminates duplicated placeholder detection logic
- */
-export function isPlaceholder(item: any): boolean {
-  return (
-    item &&
-    typeof item === "object" &&
-    (item._placeholder === true || item["_placeholder"] === true) // Support both access patterns
-  );
-}
-
-/**
- * Creates a range key for deduplication
- * Used by multiple features for tracking ranges
- */
-export function getRangeKey(range: { start: number; end: number }): string {
-  return `${range.start}-${range.end}`;
-}
-
-/**
- * Clamps a value between min and max
- * Used by multiple features for boundary checking
- */
-export function clamp(value: number, min: number, max: number): number {
-  return Math.max(min, Math.min(max, value));
-}
-
-/**
- * Stores a function reference on the component for later access
- * Eliminates pattern like (component as any)._featureFunction = fn
- */
-export function storeFeatureFunction<T extends Record<string, any>>(
-  component: T,
-  name: string,
-  fn: Function
-): void {
-  (component as any)[name] = fn;
-}