mtrl-addons 0.1.1 → 0.2.1

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

@@ -1,309 +0,0 @@
-/**
- * Virtual Scrolling Module - Core virtual scrolling calculations
- * Handles visible range calculation and total virtual size management
- */
-
-import type { ListManagerComponent, ItemRange } from "../../types";
-import type { ItemSizeManager } from "./item-size";
-// Removed calculateVisibleRangeUtil import - using unified index-based approach
-
-/**
- * Configuration for virtual scrolling
- */
-export interface VirtualConfig {
-  orientation: "vertical" | "horizontal";
-  overscan: number;
-  onDimensionsChanged?: (data: {
-    containerSize: number;
-    totalVirtualSize: number;
-    estimatedItemSize: number;
-    totalItems: number;
-  }) => void;
-}
-
-/**
- * Virtual scrolling state
- */
-export interface VirtualState {
-  totalVirtualSize: number;
-  containerSize: number;
-}
-
-/**
- * Virtual scrolling manager interface
- */
-export interface VirtualManager {
-  // Range calculations
-  calculateVisibleRange(scrollPosition: number): ItemRange;
-
-  // Size management
-  updateTotalVirtualSize(totalItems: number): void;
-  getTotalVirtualSize(): number;
-
-  // Index-based scrolling utilities
-  calculateVirtualPositionForIndex(index: number): number;
-  calculateIndexFromVirtualPosition(position: number): number;
-  getMaxScrollPosition(): number;
-
-  // State management
-  updateState(updates: Partial<VirtualState>): void;
-  getState(): VirtualState;
-}
-
-/**
- * Creates a virtual scrolling manager using index-based approach
- * This avoids browser height limitations by not creating massive DOM elements
- */
-export const createVirtualManager = (
-  component: ListManagerComponent,
-  itemSizeManager: ItemSizeManager,
-  config: VirtualConfig,
-  getTotalItems?: () => number
-): VirtualManager => {
-  const { orientation, overscan, onDimensionsChanged } = config;
-
-  // Virtual scrolling state
-  let totalVirtualSize = 0;
-  let containerSize = 0;
-
-  /**
-   * Calculate visible range based on scroll position
-   * Uses unified index-based approach for all dataset sizes
-   */
-  const calculateVisibleRange = (scrollPosition: number): ItemRange => {
-    const actualTotalItems = getTotalItems
-      ? getTotalItems()
-      : component.totalItems;
-
-    if (actualTotalItems === 0) {
-      return { start: 0, end: 0 };
-    }
-
-    // Always use index-based calculation for consistency
-    if (totalVirtualSize > 0) {
-      // Map scroll position to item index using ratio
-      const scrollRatio = Math.min(1, scrollPosition / totalVirtualSize);
-      const exactScrollIndex = scrollRatio * actualTotalItems;
-      const startIndex = Math.floor(exactScrollIndex);
-
-      // Calculate viewport size in items
-      const viewportItemCount = Math.ceil(
-        containerSize / itemSizeManager.getEstimatedItemSize()
-      );
-      const itemsInViewport = Math.floor(
-        containerSize / itemSizeManager.getEstimatedItemSize()
-      );
-
-      // Special handling for when we're near the very end
-      const maxScrollPosition = totalVirtualSize - containerSize;
-      const distanceFromBottom = maxScrollPosition - scrollPosition;
-
-      // Calculate what the last possible start index should be
-      const maxStartIndex = Math.max(0, actualTotalItems - itemsInViewport);
-
-      // Use a larger threshold (500 pixels) to ensure smooth transitions
-      // This represents about 6 items worth of scrolling
-      const bottomThreshold = 500;
-
-      if (distanceFromBottom <= bottomThreshold && distanceFromBottom >= -1) {
-        // When near the bottom, interpolate between the calculated position and the last position
-        // This ensures smooth scrolling without jumps
-
-        if (distanceFromBottom <= 1 && distanceFromBottom >= -1) {
-          // At the very bottom, show exactly the last items
-          const lastStartIndex = maxStartIndex;
-          const start = Math.max(0, lastStartIndex - overscan);
-          const end = actualTotalItems - 1;
-
-          return { start, end };
-        } else {
-          // Near the bottom but not at the very end
-          // Smoothly interpolate between normal calculation and bottom position
-          const interpolationFactor =
-            (bottomThreshold - distanceFromBottom) / bottomThreshold;
-
-          // Calculate where we would be with normal scrolling
-          let normalStartIndex = startIndex;
-          if (normalStartIndex > maxStartIndex) {
-            normalStartIndex = maxStartIndex;
-          }
-
-          // Interpolate between normal position and max position
-          const interpolatedStartIndex = Math.floor(
-            normalStartIndex +
-              (maxStartIndex - normalStartIndex) * interpolationFactor
-          );
-
-          const endIndex = Math.min(
-            interpolatedStartIndex + viewportItemCount - 1,
-            actualTotalItems - 1
-          );
-
-          // Apply overscan
-          const start = Math.max(0, interpolatedStartIndex - overscan);
-          const end = Math.min(actualTotalItems - 1, endIndex + overscan);
-
-          return { start, end };
-        }
-      }
-
-      // For positions not near the end, use normal index-based calculation
-      let adjustedStartIndex = startIndex;
-      if (startIndex > maxStartIndex) {
-        adjustedStartIndex = maxStartIndex;
-      }
-
-      const endIndex = Math.min(
-        adjustedStartIndex + viewportItemCount - 1,
-        actualTotalItems - 1
-      );
-
-      // Apply overscan
-      const start = Math.max(0, adjustedStartIndex - overscan);
-      const end = Math.min(actualTotalItems - 1, endIndex + overscan);
-
-      return { start, end };
-    }
-
-    // This should not happen as totalVirtualSize should always be > 0
-    console.warn(
-      `[VIRTUAL] Unexpected state: totalVirtualSize=${totalVirtualSize}`
-    );
-    return { start: 0, end: Math.min(10, actualTotalItems - 1) };
-  };
-
-  /**
-   * Update total virtual size based on total items
-   * Uses actual size when possible, caps at 10M pixels to prevent browser issues
-   */
-  const updateTotalVirtualSize = (totalItems: number): void => {
-    const estimatedItemSize = itemSizeManager.getEstimatedItemSize();
-
-    // Cap the virtual size at a reasonable maximum to prevent browser issues
-    // This provides smooth scrolling for any dataset size
-    const MAX_VIRTUAL_SIZE = 10 * 1000 * 1000; // 10M pixels - well within browser limits
-
-    let newTotalVirtualSize: number;
-
-    if (totalItems * estimatedItemSize > MAX_VIRTUAL_SIZE) {
-      // Cap virtual size to prevent browser issues
-      newTotalVirtualSize = MAX_VIRTUAL_SIZE;
-      // console.log(
-      //   `📐 [VIRTUAL] Capping virtual size at 10M pixels for ${totalItems.toLocaleString()} items (would be ${(
-      //     (totalItems * estimatedItemSize) /
-      //     1_000_000
-      //   ).toFixed(1)}M pixels)`
-      // );
-    } else {
-      // Use actual size when within limits
-      newTotalVirtualSize = totalItems * estimatedItemSize;
-    }
-
-    if (newTotalVirtualSize !== totalVirtualSize) {
-      totalVirtualSize = newTotalVirtualSize;
-
-      // Notify about dimensions change
-      onDimensionsChanged?.({
-        containerSize,
-        totalVirtualSize: newTotalVirtualSize,
-        estimatedItemSize,
-        totalItems,
-      });
-    }
-  };
-
-  /**
-   * Calculate virtual scroll position for a given item index
-   */
-  const calculateVirtualPositionForIndex = (index: number): number => {
-    const actualTotalItems = getTotalItems
-      ? getTotalItems()
-      : component.totalItems;
-
-    if (actualTotalItems === 0) return 0;
-
-    const itemSize = itemSizeManager.getEstimatedItemSize();
-    const actualPosition = index * itemSize;
-
-    // If using index-based scrolling, map to virtual space
-    const actualTotalSize = actualTotalItems * itemSize;
-    if (actualTotalSize > totalVirtualSize) {
-      const ratio = index / actualTotalItems;
-      return ratio * totalVirtualSize;
-    }
-
-    return actualPosition;
-  };
-
-  /**
-   * Calculate item index from virtual scroll position
-   */
-  const calculateIndexFromVirtualPosition = (position: number): number => {
-    const actualTotalItems = getTotalItems
-      ? getTotalItems()
-      : component.totalItems;
-
-    if (actualTotalItems === 0 || totalVirtualSize === 0) return 0;
-
-    const itemSize = itemSizeManager.getEstimatedItemSize();
-    const actualTotalSize = actualTotalItems * itemSize;
-
-    // If using index-based scrolling, map from virtual space
-    if (actualTotalSize > totalVirtualSize) {
-      const ratio = position / totalVirtualSize;
-      return Math.floor(ratio * actualTotalItems);
-    }
-
-    return Math.floor(position / itemSize);
-  };
-
-  /**
-   * Get maximum scroll position
-   */
-  const getMaxScrollPosition = (): number => {
-    return Math.max(0, totalVirtualSize - containerSize);
-  };
-
-  /**
-   * Get current total virtual size
-   */
-  const getTotalVirtualSize = (): number => totalVirtualSize;
-
-  /**
-   * Update virtual scrolling state
-   */
-  const updateState = (updates: Partial<VirtualState>): void => {
-    if (updates.totalVirtualSize !== undefined) {
-      totalVirtualSize = updates.totalVirtualSize;
-    }
-    if (updates.containerSize !== undefined) {
-      containerSize = updates.containerSize;
-    }
-  };
-
-  /**
-   * Get current virtual scrolling state
-   */
-  const getState = (): VirtualState => ({
-    totalVirtualSize,
-    containerSize,
-  });
-
-  return {
-    // Range calculations
-    calculateVisibleRange,
-
-    // Size management
-    updateTotalVirtualSize,
-    getTotalVirtualSize,
-
-    // Index-based scrolling utilities
-    calculateVirtualPositionForIndex,
-    calculateIndexFromVirtualPosition,
-    getMaxScrollPosition,
-
-    // State management
-    updateState,
-    getState,
-  };
-};

package/src/core/list-manager/index.ts

@@ -1,279 +0,0 @@
-/**
- * List Manager Public API
- * Main exports for the mtrl-addons List Manager system
- */
-
-// Import types first
-import type {
-  ListManager,
-  ListManagerConfig,
-  CollectionConfig,
-  ItemRange,
-  ViewportInfo,
-} from "./types";
-import { createListManager } from "./list-manager";
-import { createListManagerAPI, ListManagerAPI, ListManagerUtils } from "./api";
-
-// Export all types
-export type {
-  ListManager,
-  ListManagerConfig,
-  ListManagerConfigUpdate,
-  ListManagerObserver,
-  ListManagerUnsubscribe,
-  ItemRange,
-  ViewportInfo,
-  SpeedTracker,
-  ViewportFeature,
-  CollectionFeature,
-  FeatureContext,
-  RangeCalculationResult,
-
-  // Configuration types
-  CollectionConfig,
-  TemplateConfig,
-  VirtualConfig,
-  OrientationConfig,
-  InitialLoadConfig,
-  ErrorHandlingConfig,
-  PositioningConfig,
-  BoundariesConfig,
-  RecyclingConfig,
-  PerformanceConfig,
-  IntersectionConfig,
-
-  // Event system
-  ListManagerEventData,
-} from "./types";
-
-export { ListManagerEvents } from "./types";
-
-// Export core functions
-export { createListManager, ListManagerImpl } from "./list-manager";
-export { createListManagerAPI, ListManagerAPI, ListManagerUtils } from "./api";
-
-// Export constants
-export { LIST_MANAGER_CONSTANTS, mergeConstants } from "./constants";
-export type { ListManagerConstants } from "./constants";
-
-// Export utility functions
-export {
-  calculateTotalVirtualSize,
-  calculateContainerPosition,
-  calculateScrollPositionForIndex,
-  calculateScrollPositionForPage,
-  calculateScrollbarMetrics,
-  calculateInitialRangeSize,
-  calculateMissingRanges,
-  calculateBufferRanges,
-  clamp,
-  applyBoundaryResistance,
-} from "./utils/calculations";
-
-export {
-  createSpeedTracker,
-  updateSpeedTracker,
-  isFastScrolling,
-  isSlowScrolling,
-  getLoadingStrategy,
-  calculateScrollMomentum,
-  createSpeedBasedLoadingConfig,
-  resetSpeedTracker,
-  getScrollThrottleInterval,
-  hasSignificantDirectionChange,
-  calculateAdaptiveOverscan,
-  getSpeedTrackerDebugInfo,
-} from "./utils/speed-tracker";
-
-export {
-  calculateRangeIndex,
-  calculateRangeBounds,
-  calculateRequiredRanges,
-  calculatePrefetchRanges,
-  calculateRangeResult,
-  rangeToPaginationParams,
-  rangesToBatchParams,
-  calculateOptimalRangeSize,
-  isRangeInViewport,
-  calculateRangePriority,
-  sortRangesByPriority,
-  mergeAdjacentRanges,
-  calculateRangeCleanupCandidates,
-  calculateRangeLoadingOrder,
-  getRangeDebugInfo,
-} from "./utils/range-calculator";
-
-// Export feature factories
-export { createViewportFeature } from "./features/viewport";
-export { createCollectionFeature } from "./features/collection";
-
-/**
- * Default export - createListManager for convenience
- */
-export { createListManager as default } from "./list-manager";
-
-/**
- * Version information
- */
-export const LIST_MANAGER_VERSION = "1.0.0";
-
-/**
- * Feature compatibility flags
- */
-export const FEATURES = {
-  VIRTUAL_SCROLLING: true,
-  CUSTOM_SCROLLBAR: true,
-  SPEED_BASED_LOADING: true,
-  PLACEHOLDER_SYSTEM: true,
-  ORIENTATION_SUPPORT: true,
-  RANGE_PAGINATION: true,
-  ELEMENT_RECYCLING: false, // Phase 2
-  SMOOTH_SCROLLING: false, // Phase 2
-  PERFORMANCE_MONITORING: false, // Phase 2
-} as const;
-
-/**
- * Quick setup helpers for common use cases
- */
-export const QuickSetup = {
-  /**
-   * Create a basic vertical list with static items
-   */
-  verticalList: (
-    container: HTMLElement,
-    items: any[],
-    template: (item: any, index: number) => HTMLElement
-  ): ListManager => {
-    return createListManager({
-      container,
-      items,
-      template: { template },
-      virtual: {
-        enabled: true,
-        itemSize: "auto",
-        estimatedItemSize: 84,
-        overscan: 5,
-      },
-      orientation: {
-        orientation: "vertical",
-        reverse: false,
-        crossAxisAlignment: "stretch",
-      },
-      debug: false,
-      prefix: "mtrl-list",
-      componentName: "List",
-    });
-  },
-
-  /**
-   * Create a horizontal list with static items
-   */
-  horizontalList: (
-    container: HTMLElement,
-    items: any[],
-    template: (item: any, index: number) => HTMLElement
-  ): ListManager => {
-    return createListManager({
-      container,
-      items,
-      template: { template },
-      virtual: {
-        enabled: true,
-        itemSize: "auto",
-        estimatedItemSize: 200,
-        overscan: 3,
-      },
-      orientation: {
-        orientation: "horizontal",
-        reverse: false,
-        crossAxisAlignment: "stretch",
-      },
-      debug: false,
-      prefix: "mtrl-list",
-      componentName: "HorizontalList",
-    });
-  },
-
-  /**
-   * Create an API-driven list with collection integration
-   */
-  apiList: (
-    container: HTMLElement,
-    collection: CollectionConfig,
-    template: (item: any, index: number) => HTMLElement
-  ): ListManager => {
-    return createListManager({
-      container,
-      collection,
-      template: { template },
-      virtual: {
-        enabled: true,
-        itemSize: "auto",
-        estimatedItemSize: 60,
-        overscan: 5,
-      },
-      orientation: {
-        orientation: "vertical",
-        reverse: false,
-        crossAxisAlignment: "stretch",
-      },
-      initialLoad: {
-        strategy: "placeholders",
-        viewportMultiplier: 1.5,
-        minItems: 10,
-        maxItems: 100,
-      },
-      debug: false,
-      prefix: "mtrl-list",
-      componentName: "ApiList",
-    });
-  },
-
-  /**
-   * Create a debug list for development
-   */
-  debugList: (
-    container: HTMLElement,
-    itemCount: number = 1000
-  ): ListManagerAPI => {
-    return createListManagerAPI(
-      ListManagerUtils.createTestConfig(container, itemCount)
-    );
-  },
-};
-
-/**
- * Type guards for feature detection
- */
-export const TypeGuards = {
-  isListManager: (obj: any): obj is ListManager => {
-    return (
-      obj &&
-      typeof obj.scrollToIndex === "function" &&
-      typeof obj.getVisibleRange === "function" &&
-      typeof obj.initialize === "function"
-    );
-  },
-
-  isListManagerAPI: (obj: any): obj is ListManagerAPI => {
-    return (
-      TypeGuards.isListManager(obj) &&
-      typeof obj.onScroll === "function" &&
-      typeof obj.getDebugInfo === "function"
-    );
-  },
-
-  isItemRange: (obj: any): obj is ItemRange => {
-    return obj && typeof obj.start === "number" && typeof obj.end === "number";
-  },
-
-  isViewportInfo: (obj: any): obj is ViewportInfo => {
-    return (
-      obj &&
-      typeof obj.containerSize === "number" &&
-      typeof obj.totalVirtualSize === "number" &&
-      TypeGuards.isItemRange(obj.visibleRange) &&
-      typeof obj.virtualScrollPosition === "number"
-    );
-  },
-};