mtrl-addons 0.1.2 → 0.2.2

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

@@ -0,0 +1,130 @@
+// 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/index.ts

@@ -0,0 +1,20 @@
+// src/core/list-manager/features/viewport/index.ts
+
+export { withBase } from "./base";
+export { withCollection } from "./collection";
+export { withEvents } from "./events";
+export { withPlaceholders } from "./placeholders";
+export { withRendering } from "./rendering";
+export { withScrollbar } from "./scrollbar";
+export { withScrolling } from "./scrolling";
+export { withVirtual } from "./virtual";
+export { withPerformance } from "./performance";
+export { withMomentum } from "./momentum";
+
+// Utility exports
+export { createItemSizeManager } from "./item-size";
+export { createLoadingManager } from "./loading";
+// No createElementFromTemplate util here; remove incorrect export
+
+// Types
+export type { PlaceholderComponent, PlaceholderConfig } from "./placeholders";

package/src/core/{list-manager/features/viewport → viewport/features}/item-size.ts

@@ -9,7 +9,7 @@ export interface ItemSizeManager {
   measureItem(
     element: HTMLElement,
     index: number,
-    orientation?: "vertical" | "horizontal"
+    orientation?: "vertical" | "horizontal",
   ): number;
 
   // Cache management
@@ -20,8 +20,8 @@ export interface ItemSizeManager {
   clearCache(): void;
 
   // Size estimation
-  getEstimatedItemSize(): number;
-  updateEstimatedSize(): void;
+  getItemSize(): number;
+  updateItemSize(): void;
 
   // Additional utilities
   calculateTotalSize(totalItems?: number): number;
@@ -29,7 +29,7 @@ export interface ItemSizeManager {
 
   // Callbacks
   onSizeUpdated?: (totalSize: number) => void;
-  onEstimatedSizeChanged?: (newEstimate: number) => void;
+  onItemSizeChanged?: (newEstimate: number) => void;
 }
 
 export interface ItemSizeConfig {
@@ -37,26 +37,26 @@ export interface ItemSizeConfig {
   orientation?: "vertical" | "horizontal";
   cacheSize?: number;
   onSizeUpdated?: (totalSize: number) => void;
-  onEstimatedSizeChanged?: (newEstimate: number) => void;
+  onItemSizeChanged?: (newEstimate: number) => void;
 }
 
 /**
  * Creates an item size manager for measuring and caching item dimensions
  */
 export const createItemSizeManager = (
-  config: ItemSizeConfig = {}
+  config: ItemSizeConfig = {},
 ): ItemSizeManager => {
   const {
     initialEstimate = 60,
     orientation = "vertical",
     cacheSize = 1000,
     onSizeUpdated,
-    onEstimatedSizeChanged,
+    onItemSizeChanged,
   } = config;
 
   // Size cache - stores actual measured sizes
   const measuredSizes = new Map<number, number>();
-  let currentEstimatedItemSize = initialEstimate;
+  let currentItemSize = initialEstimate;
 
   // Batching state for performance optimization
   let batchUpdateTimeout: number | null = null;
@@ -82,7 +82,7 @@ export const createItemSizeManager = (
    */
   const triggerBatchedUpdates = (): void => {
     // Update estimated size based on all measurements
-    updateEstimatedSize();
+    updateItemSize();
 
     // Notify about total size update
     if (onSizeUpdated) {
@@ -116,10 +116,10 @@ export const createItemSizeManager = (
   const measureItem = (
     element: HTMLElement,
     index: number,
-    measureOrientation?: "vertical" | "horizontal"
+    measureOrientation?: "vertical" | "horizontal",
   ): number => {
     if (!element || index < 0) {
-      return currentEstimatedItemSize;
+      return currentItemSize;
     }
 
     const actualOrientation = measureOrientation || orientation;
@@ -144,13 +144,13 @@ export const createItemSizeManager = (
       return size;
     }
 
-    return currentEstimatedItemSize;
+    return currentItemSize;
   };
 
   /**
    * Update estimated item size based on measured sizes (with change threshold)
    */
-  const updateEstimatedSize = (): void => {
+  const updateItemSize = (): void => {
     if (measuredSizes.size === 0) return;
 
     const sizes = Array.from(measuredSizes.values());
@@ -158,22 +158,19 @@ export const createItemSizeManager = (
     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(currentEstimatedItemSize * 0.05)
-    );
-    const absoluteChange = Math.abs(newEstimate - currentEstimatedItemSize);
+    const changeThreshold = Math.max(2, Math.round(currentItemSize * 0.05));
+    const absoluteChange = Math.abs(newEstimate - currentItemSize);
 
     if (absoluteChange >= changeThreshold) {
-      const previousEstimate = currentEstimatedItemSize;
-      currentEstimatedItemSize = newEstimate;
+      const previousEstimate = currentItemSize;
+      currentItemSize = newEstimate;
 
-      if (onEstimatedSizeChanged) {
-        onEstimatedSizeChanged(newEstimate);
+      if (onItemSizeChanged) {
+        onItemSizeChanged(newEstimate);
       }
     } else if (absoluteChange > 0) {
       // Silent update for small changes
-      currentEstimatedItemSize = newEstimate;
+      currentItemSize = newEstimate;
     }
   };
 
@@ -185,13 +182,13 @@ export const createItemSizeManager = (
       // Calculate based on measured items only
       return Array.from(measuredSizes.values()).reduce(
         (sum, size) => sum + size,
-        0
+        0,
       );
     }
 
     let totalSize = 0;
     for (let i = 0; i < totalItems; i++) {
-      totalSize += measuredSizes.get(i) || currentEstimatedItemSize;
+      totalSize += measuredSizes.get(i) || currentItemSize;
     }
     return totalSize;
   };
@@ -200,7 +197,7 @@ export const createItemSizeManager = (
    * Get size for a specific item (measured or estimated)
    */
   const getMeasuredSize = (index: number): number => {
-    return measuredSizes.get(index) || currentEstimatedItemSize;
+    return measuredSizes.get(index) || currentItemSize;
   };
 
   /**
@@ -221,8 +218,8 @@ export const createItemSizeManager = (
   /**
    * Get current estimated item size
    */
-  const getEstimatedItemSize = (): number => {
-    return currentEstimatedItemSize;
+  const getItemSize = (): number => {
+    return currentItemSize;
   };
 
   /**
@@ -238,16 +235,16 @@ export const createItemSizeManager = (
   const getStats = () => {
     return {
       cachedItems: measuredSizes.size,
-      estimatedSize: currentEstimatedItemSize,
+      estimatedSize: currentItemSize,
       cacheSize: cacheSize,
       minSize:
         measuredSizes.size > 0
           ? Math.min(...measuredSizes.values())
-          : currentEstimatedItemSize,
+          : currentItemSize,
       maxSize:
         measuredSizes.size > 0
           ? Math.max(...measuredSizes.values())
-          : currentEstimatedItemSize,
+          : currentItemSize,
       orientation: orientation,
     };
   };
@@ -259,8 +256,8 @@ export const createItemSizeManager = (
     getMeasuredSize,
     getMeasuredSizes,
     clearCache,
-    getEstimatedItemSize,
-    updateEstimatedSize,
+    getItemSize,
+    updateItemSize,
     cacheItemSize,
 
     // Additional utilities
@@ -269,6 +266,6 @@ export const createItemSizeManager = (
 
     // Callbacks
     onSizeUpdated,
-    onEstimatedSizeChanged,
+    onItemSizeChanged,
   };
 };

package/src/core/{list-manager/features/viewport → viewport/features}/loading.ts

@@ -5,9 +5,9 @@
  * When scrolling fast, it cancels loads to prevent server overload.
  */
 
-import type { ListManagerComponent, ItemRange } from "../../types";
-import { LIST_MANAGER_CONSTANTS } from "../../constants";
-import { VIEWPORT_CONSTANTS } from "./constants";
+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
@@ -196,7 +196,7 @@ export const createLoadingManager = (
     const collection = (component as any).collection;
     if (collection && typeof collection.loadMissingRanges === "function") {
       collection
-        .loadMissingRanges(range)
+        .loadMissingRanges(range, "loading:loadRange")
         .then(() => {
           activeRequests--;
           activeRanges.delete(rangeKey);

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

@@ -0,0 +1,269 @@
+// src/core/viewport/features/momentum.ts
+
+/**
+ * Momentum Feature - Adds inertial scrolling to viewport
+ * Provides smooth deceleration after touch/mouse drag gestures
+ */
+
+import type { ViewportComponent, ViewportContext } from "../types";
+import { VIEWPORT_CONSTANTS } from "../constants";
+
+interface MomentumConfig {
+  enabled?: boolean;
+  deceleration?: number;
+  minVelocity?: number;
+  minDuration?: number;
+  minVelocityThreshold?: number;
+}
+
+/**
+ * Adds momentum scrolling to viewport
+ */
+export const withMomentum = (config: MomentumConfig = {}) => {
+  return <T extends ViewportContext & ViewportComponent>(component: T): T => {
+    const {
+      enabled = VIEWPORT_CONSTANTS.MOMENTUM.ENABLED,
+      deceleration = VIEWPORT_CONSTANTS.MOMENTUM.DECELERATION_FACTOR,
+      minVelocity = VIEWPORT_CONSTANTS.MOMENTUM.MIN_VELOCITY,
+      minDuration = VIEWPORT_CONSTANTS.MOMENTUM.MIN_DURATION,
+      minVelocityThreshold = VIEWPORT_CONSTANTS.MOMENTUM.MIN_VELOCITY_THRESHOLD,
+    } = config;
+
+    // Always apply the feature, but check isEnabled at runtime
+
+    // Momentum state
+    let momentumAnimationId: number | null = null;
+    let isTouching = false;
+    let isMouseDragging = false;
+    let lastTouchPosition = 0;
+    let lastMousePosition = 0;
+    let touchStartTime = 0;
+    let viewportState: any;
+    let scrollingState: any;
+    let isEnabled = enabled; // Track current enabled state
+
+    // Get references after initialization
+    const originalInitialize = component.viewport.initialize;
+    component.viewport.initialize = () => {
+      const result = originalInitialize();
+      // Skip if already initialized
+      if (result === false) {
+        return false;
+      }
+
+      // Get viewport and scrolling states
+      viewportState = (component.viewport as any).state;
+      scrollingState = (component.viewport as any).scrollingState;
+      return result;
+    };
+
+    // Start momentum animation
+    const startMomentum = (initialVelocity: number) => {
+      // Cancel any existing momentum
+      if (momentumAnimationId) {
+        cancelAnimationFrame(momentumAnimationId);
+      }
+
+      let velocity = initialVelocity;
+
+      const animate = () => {
+        // Apply deceleration
+        velocity *= deceleration;
+
+        // Stop if velocity is too small
+        if (Math.abs(velocity) < minVelocity) {
+          momentumAnimationId = null;
+          // Reset velocity in scrolling feature
+          if (scrollingState) {
+            scrollingState.setVelocityToZero?.();
+          }
+          return;
+        }
+
+        // Calculate scroll delta (velocity is in px/ms, so multiply by frame time)
+        const frameDelta = velocity * VIEWPORT_CONSTANTS.MOMENTUM.FRAME_TIME;
+
+        // Use scrolling feature's API to update position
+        if (component.viewport.scrollBy) {
+          component.viewport.scrollBy(frameDelta);
+
+          // Continue animation
+          momentumAnimationId = requestAnimationFrame(animate);
+        } else {
+          // No scrollBy method, stop momentum
+          momentumAnimationId = null;
+        }
+      };
+
+      momentumAnimationId = requestAnimationFrame(animate);
+    };
+
+    // Touch event handlers
+    const handleTouchStart = (e: TouchEvent) => {
+      isTouching = true;
+      const touch = e.touches[0];
+      const orientation = viewportState?.orientation || "vertical";
+      lastTouchPosition =
+        orientation === "vertical" ? touch.clientY : touch.clientX;
+      touchStartTime = Date.now();
+
+      // Cancel any ongoing momentum
+      if (momentumAnimationId) {
+        cancelAnimationFrame(momentumAnimationId);
+        momentumAnimationId = null;
+      }
+    };
+
+    const handleTouchMove = (e: TouchEvent) => {
+      if (!isTouching) return;
+
+      e.preventDefault(); // Prevent native scrolling
+
+      const touch = e.touches[0];
+      const orientation = viewportState?.orientation || "vertical";
+      const currentPosition =
+        orientation === "vertical" ? touch.clientY : touch.clientX;
+      const delta = lastTouchPosition - currentPosition; // Inverted for natural scrolling
+      lastTouchPosition = currentPosition;
+
+      // Use scrolling feature's API
+      if (component.viewport.scrollBy) {
+        component.viewport.scrollBy(delta);
+      }
+    };
+
+    const handleTouchEnd = () => {
+      if (!isTouching) return;
+      isTouching = false;
+
+      const touchEndTime = Date.now();
+      const touchDuration = touchEndTime - touchStartTime;
+
+      // Get current velocity from scrolling feature
+      const velocity = component.viewport.getVelocity?.() || 0;
+
+      // Only start momentum if the touch was quick enough and we have velocity
+      if (
+        touchDuration < minDuration &&
+        Math.abs(velocity) > minVelocityThreshold
+      ) {
+        startMomentum(velocity);
+      }
+    };
+
+    // Mouse event handlers for desktop
+    const handleMouseDown = (e: MouseEvent) => {
+      isMouseDragging = true;
+      const orientation = viewportState?.orientation || "vertical";
+      lastMousePosition = orientation === "vertical" ? e.clientY : e.clientX;
+      touchStartTime = Date.now();
+
+      // Cancel any ongoing momentum
+      if (momentumAnimationId) {
+        cancelAnimationFrame(momentumAnimationId);
+        momentumAnimationId = null;
+      }
+
+      // Prevent text selection
+      e.preventDefault();
+    };
+
+    const handleMouseMove = (e: MouseEvent) => {
+      if (!isMouseDragging) return;
+
+      const orientation = viewportState?.orientation || "vertical";
+      const currentPosition =
+        orientation === "vertical" ? e.clientY : e.clientX;
+      const delta = lastMousePosition - currentPosition;
+      lastMousePosition = currentPosition;
+
+      // Use scrolling feature's API
+      if (component.viewport.scrollBy) {
+        component.viewport.scrollBy(delta);
+      }
+    };
+
+    const handleMouseUp = () => {
+      if (!isMouseDragging) return;
+      isMouseDragging = false;
+
+      const mouseUpTime = Date.now();
+      const dragDuration = mouseUpTime - touchStartTime;
+
+      // Get current velocity from scrolling feature
+      const velocity = component.viewport.getVelocity?.() || 0;
+
+      // Start momentum for quick drags
+      if (
+        dragDuration < minDuration &&
+        Math.abs(velocity) > minVelocityThreshold
+      ) {
+        startMomentum(velocity);
+      }
+    };
+
+    // Override initialize to add event listeners
+    const originalInit = component.viewport.initialize;
+    component.viewport.initialize = () => {
+      const result = originalInit();
+      // Skip if already initialized
+      if (result === false) {
+        return false;
+      }
+
+      const viewportElement =
+        (component as any).viewportElement ||
+        (component.viewport as any).state?.viewportElement;
+
+      if (viewportElement) {
+        // Touch events
+        viewportElement.addEventListener("touchstart", handleTouchStart, {
+          passive: true,
+        });
+        viewportElement.addEventListener("touchmove", handleTouchMove, {
+          passive: false,
+        });
+        viewportElement.addEventListener("touchend", handleTouchEnd, {
+          passive: true,
+        });
+
+        // Mouse events for desktop dragging
+        viewportElement.addEventListener("mousedown", handleMouseDown);
+        viewportElement.addEventListener("mousemove", handleMouseMove);
+        viewportElement.addEventListener("mouseup", handleMouseUp);
+        viewportElement.addEventListener("mouseleave", handleMouseUp);
+
+        // Store reference for cleanup
+        (component as any)._momentumViewportElement = viewportElement;
+      }
+    };
+
+    // 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)._momentumViewportElement;
+        if (viewportElement) {
+          viewportElement.removeEventListener("touchstart", handleTouchStart);
+          viewportElement.removeEventListener("touchmove", handleTouchMove);
+          viewportElement.removeEventListener("touchend", handleTouchEnd);
+          viewportElement.removeEventListener("mousedown", handleMouseDown);
+          viewportElement.removeEventListener("mousemove", handleMouseMove);
+          viewportElement.removeEventListener("mouseup", handleMouseUp);
+          viewportElement.removeEventListener("mouseleave", handleMouseUp);
+        }
+
+        // Cancel momentum animation
+        if (momentumAnimationId) {
+          cancelAnimationFrame(momentumAnimationId);
+          momentumAnimationId = null;
+        }
+
+        originalDestroy();
+      };
+    }
+
+    return component;
+  };
+};