mtrl-addons 0.2.2 → 0.2.4

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

@@ -1,130 +0,0 @@
-// src/core/viewport/features/events.ts
-
-/**
- * Events Feature - Centralized event system for viewport
- * Provides event emission and subscription for inter-feature communication
- */
-
-import type { ViewportContext, ViewportComponent } from "../types";
-
-export interface EventsConfig {
-  debug?: boolean;
-}
-
-/**
- * Events feature for viewport
- * Centralizes all event handling for viewport features
- */
-export const withEvents = (config: EventsConfig = {}) => {
-  return <T extends ViewportContext & ViewportComponent>(component: T): T => {
-    const { debug = false } = config;
-
-    // Event listeners map
-    const listeners = new Map<string, Set<Function>>();
-
-    // Emit an event
-    const emit = (event: string, data?: any) => {
-      // if (debug) {
-      //   console.log(`[Events] Emit: ${event}`, data);
-      // }
-
-      const eventListeners = listeners.get(event);
-      if (eventListeners) {
-        eventListeners.forEach((listener) => {
-          try {
-            listener(data);
-          } catch (error) {
-            console.error(`[Events] Error in listener for ${event}:`, error);
-          }
-        });
-      }
-    };
-
-    // Subscribe to an event
-    const on = (event: string, handler: Function): (() => void) => {
-      if (!listeners.has(event)) {
-        listeners.set(event, new Set());
-      }
-
-      listeners.get(event)!.add(handler);
-
-      // if (debug) {
-      //   console.log(`[Events] Subscribed to: ${event}`);
-      // }
-
-      // Return unsubscribe function
-      return () => {
-        const eventListeners = listeners.get(event);
-        if (eventListeners) {
-          eventListeners.delete(handler);
-          if (eventListeners.size === 0) {
-            listeners.delete(event);
-          }
-        }
-      };
-    };
-
-    // Subscribe to an event once
-    const once = (event: string, handler: Function): (() => void) => {
-      const wrappedHandler = (data: any) => {
-        handler(data);
-        off(event, wrappedHandler);
-      };
-      return on(event, wrappedHandler);
-    };
-
-    // Unsubscribe from an event
-    const off = (event: string, handler: Function) => {
-      const eventListeners = listeners.get(event);
-      if (eventListeners) {
-        eventListeners.delete(handler);
-        if (eventListeners.size === 0) {
-          listeners.delete(event);
-        }
-      }
-    };
-
-    // Clear all listeners for an event
-    const clear = (event?: string) => {
-      if (event) {
-        listeners.delete(event);
-      } else {
-        listeners.clear();
-      }
-    };
-
-    // Add event methods to component
-    component.emit = emit;
-    component.on = on;
-    component.once = once;
-    component.off = off;
-
-    // Add events API to viewport
-    (component.viewport as any).events = {
-      emit,
-      on,
-      once,
-      off,
-      clear,
-      getListenerCount: (event?: string) => {
-        if (event) {
-          return listeners.get(event)?.size || 0;
-        }
-        let total = 0;
-        listeners.forEach((set) => (total += set.size));
-        return total;
-      },
-    };
-
-    // Clean up on destroy
-    if ("destroy" in component && typeof component.destroy === "function") {
-      const originalDestroy = component.destroy;
-      component.destroy = () => {
-        clear();
-        originalDestroy?.();
-      };
-    }
-
-    return component;
-  };
-};

package/src/core/viewport/features/item-size.ts

@@ -1,271 +0,0 @@
-/**
- * Item Size Management
- * Handles item measurement, caching, and size estimation for virtual scrolling
- * Works with both vertical (height) and horizontal (width) orientations
- */
-
-export interface ItemSizeManager {
-  // Measurement
-  measureItem(
-    element: HTMLElement,
-    index: number,
-    orientation?: "vertical" | "horizontal",
-  ): number;
-
-  // Cache management
-  hasMeasuredSize(index: number): boolean;
-  getMeasuredSize(index: number): number;
-  getMeasuredSizes(): Map<number, number>;
-  cacheItemSize(index: number, size: number): void;
-  clearCache(): void;
-
-  // Size estimation
-  getItemSize(): number;
-  updateItemSize(): void;
-
-  // Additional utilities
-  calculateTotalSize(totalItems?: number): number;
-  getStats(): any;
-
-  // Callbacks
-  onSizeUpdated?: (totalSize: number) => void;
-  onItemSizeChanged?: (newEstimate: number) => void;
-}
-
-export interface ItemSizeConfig {
-  initialEstimate?: number;
-  orientation?: "vertical" | "horizontal";
-  cacheSize?: number;
-  onSizeUpdated?: (totalSize: number) => void;
-  onItemSizeChanged?: (newEstimate: number) => void;
-}
-
-/**
- * Creates an item size manager for measuring and caching item dimensions
- */
-export const createItemSizeManager = (
-  config: ItemSizeConfig = {},
-): ItemSizeManager => {
-  const {
-    initialEstimate = 60,
-    orientation = "vertical",
-    cacheSize = 1000,
-    onSizeUpdated,
-    onItemSizeChanged,
-  } = config;
-
-  // Size cache - stores actual measured sizes
-  const measuredSizes = new Map<number, number>();
-  let currentItemSize = initialEstimate;
-
-  // Batching state for performance optimization
-  let batchUpdateTimeout: number | null = null;
-  let pendingMeasurements = 0;
-  let batchStartTime = 0;
-
-  /**
-   * Cache a specific item size with cache size management
-   */
-  const cacheItemSize = (index: number, size: number): void => {
-    if (measuredSizes.size >= cacheSize) {
-      // Remove oldest entries (10% of cache size)
-      const entries = Array.from(measuredSizes.entries());
-      entries.slice(0, Math.floor(cacheSize * 0.1)).forEach(([key]) => {
-        measuredSizes.delete(key);
-      });
-    }
-    measuredSizes.set(index, size);
-  };
-
-  /**
-   * Trigger batched updates after measurements are complete
-   */
-  const triggerBatchedUpdates = (): void => {
-    // Update estimated size based on all measurements
-    updateItemSize();
-
-    // Notify about total size update
-    if (onSizeUpdated) {
-      const totalSize = calculateTotalSize();
-      onSizeUpdated(totalSize);
-    }
-
-    // Reset batch state
-    pendingMeasurements = 0;
-    batchUpdateTimeout = null;
-  };
-
-  /**
-   * Schedule batched updates (debounced)
-   */
-  const scheduleBatchedUpdates = (): void => {
-    if (batchUpdateTimeout) {
-      clearTimeout(batchUpdateTimeout);
-    }
-
-    // Short timeout to batch rapid measurements
-    batchUpdateTimeout = window.setTimeout(() => {
-      const batchDuration = Date.now() - batchStartTime;
-      triggerBatchedUpdates();
-    }, 16); // ~1 frame delay to batch measurements
-  };
-
-  /**
-   * Measure actual item size and update cache (with batching)
-   */
-  const measureItem = (
-    element: HTMLElement,
-    index: number,
-    measureOrientation?: "vertical" | "horizontal",
-  ): number => {
-    if (!element || index < 0) {
-      return currentItemSize;
-    }
-
-    const actualOrientation = measureOrientation || orientation;
-    const size =
-      actualOrientation === "vertical"
-        ? element.offsetHeight
-        : element.offsetWidth;
-
-    if (size > 0) {
-      const previousSize = measuredSizes.get(index);
-      cacheItemSize(index, size);
-
-      // Track batch state
-      if (pendingMeasurements === 0) {
-        batchStartTime = Date.now();
-      }
-      pendingMeasurements++;
-
-      // Schedule batched updates instead of immediate callbacks
-      scheduleBatchedUpdates();
-
-      return size;
-    }
-
-    return currentItemSize;
-  };
-
-  /**
-   * Update estimated item size based on measured sizes (with change threshold)
-   */
-  const updateItemSize = (): void => {
-    if (measuredSizes.size === 0) return;
-
-    const sizes = Array.from(measuredSizes.values());
-    const average = sizes.reduce((sum, size) => sum + size, 0) / sizes.length;
-    const newEstimate = Math.max(1, Math.round(average));
-
-    // Only update if the change is significant (>2px or >5% change)
-    const changeThreshold = Math.max(2, Math.round(currentItemSize * 0.05));
-    const absoluteChange = Math.abs(newEstimate - currentItemSize);
-
-    if (absoluteChange >= changeThreshold) {
-      const previousEstimate = currentItemSize;
-      currentItemSize = newEstimate;
-
-      if (onItemSizeChanged) {
-        onItemSizeChanged(newEstimate);
-      }
-    } else if (absoluteChange > 0) {
-      // Silent update for small changes
-      currentItemSize = newEstimate;
-    }
-  };
-
-  /**
-   * Calculate total size for a given number of items
-   */
-  const calculateTotalSize = (totalItems?: number): number => {
-    if (!totalItems) {
-      // Calculate based on measured items only
-      return Array.from(measuredSizes.values()).reduce(
-        (sum, size) => sum + size,
-        0,
-      );
-    }
-
-    let totalSize = 0;
-    for (let i = 0; i < totalItems; i++) {
-      totalSize += measuredSizes.get(i) || currentItemSize;
-    }
-    return totalSize;
-  };
-
-  /**
-   * Get size for a specific item (measured or estimated)
-   */
-  const getMeasuredSize = (index: number): number => {
-    return measuredSizes.get(index) || currentItemSize;
-  };
-
-  /**
-   * Check if item has been measured
-   */
-  const hasMeasuredSize = (index: number): boolean => {
-    return measuredSizes.has(index);
-  };
-
-  /**
-   * Clear all cached measurements
-   */
-  const clearCache = (): void => {
-    const cacheSize = measuredSizes.size;
-    measuredSizes.clear();
-  };
-
-  /**
-   * Get current estimated item size
-   */
-  const getItemSize = (): number => {
-    return currentItemSize;
-  };
-
-  /**
-   * Get all measured sizes (for compatibility)
-   */
-  const getMeasuredSizes = (): Map<number, number> => {
-    return new Map(measuredSizes);
-  };
-
-  /**
-   * Get cache statistics
-   */
-  const getStats = () => {
-    return {
-      cachedItems: measuredSizes.size,
-      estimatedSize: currentItemSize,
-      cacheSize: cacheSize,
-      minSize:
-        measuredSizes.size > 0
-          ? Math.min(...measuredSizes.values())
-          : currentItemSize,
-      maxSize:
-        measuredSizes.size > 0
-          ? Math.max(...measuredSizes.values())
-          : currentItemSize,
-      orientation: orientation,
-    };
-  };
-
-  return {
-    // Core API
-    measureItem,
-    hasMeasuredSize,
-    getMeasuredSize,
-    getMeasuredSizes,
-    clearCache,
-    getItemSize,
-    updateItemSize,
-    cacheItemSize,
-
-    // Additional utilities
-    calculateTotalSize,
-    getStats,
-
-    // Callbacks
-    onSizeUpdated,
-    onItemSizeChanged,
-  };
-};

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

@@ -1,263 +0,0 @@
-/**
- * Loading - Velocity-based intelligent data loading for viewport
- *
- * This viewport module manages data loading based on scroll velocity.
- * When scrolling fast, it cancels loads to prevent server overload.
- */
-
-import type { ItemRange } from "../types";
-type ListManagerComponent = any;
-import { VIEWPORT_CONSTANTS } from "../constants";
-
-export interface LoadingConfig {
-  cancelLoadThreshold?: number; // Velocity (px/ms) above which all loads are cancelled
-  maxConcurrentRequests?: number;
-  enableRequestQueue?: boolean;
-}
-
-export interface LoadingManager {
-  requestLoad(range: ItemRange, priority: "high" | "normal" | "low"): void;
-  updateVelocity(velocity: number, direction: "forward" | "backward"): void;
-  cancelPendingLoads(): void;
-  getStats(): LoadingStats;
-  isRangeLoading(range: ItemRange): boolean;
-}
-
-interface LoadingStats {
-  pendingRequests: number;
-  completedRequests: number;
-  failedRequests: number;
-  cancelledRequests: number;
-  currentVelocity: number;
-  canLoad: boolean;
-  queuedRequests: number;
-}
-
-interface QueuedRequest {
-  range: ItemRange;
-  priority: "high" | "normal" | "low";
-  timestamp: number;
-}
-
-/**
- * Creates a loading manager that handles data loading based on scroll velocity
- */
-export const createLoadingManager = (
-  component: ListManagerComponent,
-  config: LoadingConfig = {}
-): LoadingManager => {
-  const {
-    cancelLoadThreshold = VIEWPORT_CONSTANTS.LOADING.CANCEL_THRESHOLD,
-    maxConcurrentRequests = VIEWPORT_CONSTANTS.REQUEST_QUEUE
-      .MAX_ACTIVE_REQUESTS,
-    enableRequestQueue = VIEWPORT_CONSTANTS.REQUEST_QUEUE.ENABLED,
-  } = config;
-
-  // State
-  let currentVelocity = 0;
-  let scrollDirection: "forward" | "backward" = "forward";
-  let activeRequests = 0;
-
-  // Request queue
-  let requestQueue: QueuedRequest[] = [];
-
-  // Track active requests to prevent duplicates
-  const activeRanges = new Set<string>();
-
-  // Stats
-  let completedRequests = 0;
-  let failedRequests = 0;
-  let cancelledRequests = 0;
-
-  /**
-   * Get range key for deduplication
-   */
-  const getRangeKey = (range: ItemRange): string => {
-    return `${range.start}-${range.end}`;
-  };
-
-  /**
-   * Check if we should load data at current velocity
-   */
-  const canLoad = (): boolean => {
-    return currentVelocity <= cancelLoadThreshold;
-  };
-
-  /**
-   * Update current velocity
-   */
-  const updateVelocity = (
-    velocity: number,
-    direction: "forward" | "backward"
-  ): void => {
-    const previousVelocity = currentVelocity;
-    currentVelocity = Math.abs(velocity);
-    scrollDirection = direction;
-
-    // When velocity drops below threshold (including reaching zero), process queued requests
-    if (
-      previousVelocity > cancelLoadThreshold &&
-      currentVelocity <= cancelLoadThreshold
-    ) {
-      processQueue();
-    }
-  };
-
-  /**
-   * Process the request queue
-   */
-  const processQueue = (): void => {
-    if (!enableRequestQueue) {
-      return;
-    }
-
-    let processed = 0;
-    while (requestQueue.length > 0 && activeRequests < maxConcurrentRequests) {
-      const request = requestQueue.shift();
-      if (request) {
-        executeLoad(request.range, request.priority);
-        processed++;
-      }
-    }
-  };
-
-  /**
-   * Request to load a range with priority
-   */
-  const requestLoad = (
-    range: ItemRange,
-    priority: "high" | "normal" | "low"
-  ): void => {
-    const rangeKey = getRangeKey(range);
-
-    // Check if already loading this range
-    if (activeRanges.has(rangeKey)) {
-      return;
-    }
-
-    // Check velocity for all requests
-    if (!canLoad()) {
-      // console.log(
-      //   `🚫 [LOADING] Request cancelled - velocity ${currentVelocity.toFixed(
-      //     2
-      //   )} px/ms exceeds threshold ${cancelLoadThreshold} px/ms`
-      // );
-      cancelledRequests++;
-      return;
-    }
-
-    // For higher velocities or zero velocity, execute immediately
-    // If velocity is low, execute immediately
-    if (activeRequests < maxConcurrentRequests) {
-      executeLoad(range, priority);
-    } else if (enableRequestQueue) {
-      // Add to queue if we're at capacity
-      requestQueue.push({
-        range,
-        priority,
-        timestamp: Date.now(),
-      });
-
-      // Enforce max queue size
-      if (
-        requestQueue.length > VIEWPORT_CONSTANTS.REQUEST_QUEUE.MAX_QUEUE_SIZE
-      ) {
-        const removed = requestQueue.splice(
-          0,
-          requestQueue.length - VIEWPORT_CONSTANTS.REQUEST_QUEUE.MAX_QUEUE_SIZE
-        );
-        cancelledRequests += removed.length;
-      }
-    } else {
-      // Queue is disabled and we're at capacity - drop the request
-
-      cancelledRequests++;
-    }
-  };
-
-  /**
-   * Execute load immediately
-   */
-  const executeLoad = (
-    range: ItemRange,
-    priority: "high" | "normal" | "low"
-  ): void => {
-    const rangeKey = getRangeKey(range);
-
-    // Double-check for duplicates
-    if (activeRanges.has(rangeKey)) {
-      return;
-    }
-
-    activeRequests++;
-    activeRanges.add(rangeKey);
-
-    // Request data from collection
-    const collection = (component as any).collection;
-    if (collection && typeof collection.loadMissingRanges === "function") {
-      collection
-        .loadMissingRanges(range, "loading:loadRange")
-        .then(() => {
-          activeRequests--;
-          activeRanges.delete(rangeKey);
-          completedRequests++;
-          // Process more requests from queue
-          processQueue();
-        })
-        .catch((error: any) => {
-          activeRequests--;
-          activeRanges.delete(rangeKey);
-          failedRequests++;
-          // Process more requests from queue even on failure
-          processQueue();
-        });
-    } else {
-      activeRequests--;
-      activeRanges.delete(rangeKey);
-    }
-  };
-
-  /**
-   * Cancel all pending loads
-   */
-  const cancelPendingLoads = (): void => {
-    const count = requestQueue.length;
-    if (count > 0) {
-      cancelledRequests += count;
-      requestQueue = [];
-    }
-  };
-
-  /**
-   * Check if a range is already being loaded
-   */
-  const isRangeLoading = (range: ItemRange): boolean => {
-    const rangeKey = getRangeKey(range);
-    return activeRanges.has(rangeKey);
-  };
-
-  /**
-   * Get loading statistics
-   */
-  const getStats = (): LoadingStats => {
-    const stats = {
-      pendingRequests: activeRequests,
-      completedRequests,
-      failedRequests,
-      cancelledRequests,
-      currentVelocity,
-      canLoad: canLoad(),
-      queuedRequests: requestQueue.length,
-    };
-
-    return stats;
-  };
-
-  return {
-    requestLoad,
-    updateVelocity,
-    cancelPendingLoads,
-    getStats,
-    isRangeLoading,
-  };
-};