mtrl-addons 0.2.1 → 0.2.2

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

@@ -40,7 +40,7 @@ const createSpeedTracker = (): SpeedTracker => ({
 const updateSpeedTracker = (
   tracker: SpeedTracker,
   newPosition: number,
-  previousPosition: number
+  previousPosition: number,
 ): SpeedTracker => {
   const now = Date.now();
   const timeDelta = now - tracker.lastTime;
@@ -112,9 +112,10 @@ export const withScrolling = (config: ScrollingConfig = {}) => {
       if (viewportState) {
         totalVirtualSize = viewportState.virtualTotalSize || 0;
         containerSize = viewportState.containerSize || 0;
-        // console.log(
-        //   `[Scrolling] Initialized with totalVirtualSize: ${totalVirtualSize}, containerSize: ${containerSize}`
-        // );
+        // Sync scrollPosition from viewportState (important for initialScrollIndex)
+        if (viewportState.scrollPosition > 0) {
+          scrollPosition = viewportState.scrollPosition;
+        }
       }
 
       // Listen for virtual size changes
@@ -123,6 +124,17 @@ export const withScrolling = (config: ScrollingConfig = {}) => {
         updateScrollBounds(data.totalVirtualSize, containerSize);
       });
 
+      // Listen for scroll position changes from other features (e.g., virtual.ts after item size detection)
+      component.on?.("viewport:scroll-position-sync", (data: any) => {
+        if (data.position !== undefined && data.position !== scrollPosition) {
+          scrollPosition = data.position;
+          // Also update local tracking vars
+          totalVirtualSize =
+            viewportState?.virtualTotalSize || totalVirtualSize;
+          containerSize = viewportState?.containerSize || containerSize;
+        }
+      });
+
       // Listen for container size changes
       component.on?.("viewport:container-size-changed", (data: any) => {
         if (data.containerSize) {
@@ -239,10 +251,6 @@ export const withScrolling = (config: ScrollingConfig = {}) => {
 
       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();
@@ -260,7 +268,7 @@ export const withScrolling = (config: ScrollingConfig = {}) => {
         speedTracker = updateSpeedTracker(
           speedTracker,
           scrollPosition,
-          previousPosition
+          previousPosition,
         );
 
         // Update viewport state
@@ -306,7 +314,7 @@ export const withScrolling = (config: ScrollingConfig = {}) => {
         speedTracker = updateSpeedTracker(
           speedTracker,
           scrollPosition,
-          previousPosition
+          previousPosition,
         );
 
         // Update viewport state
@@ -352,7 +360,7 @@ export const withScrolling = (config: ScrollingConfig = {}) => {
     // Scroll to index
     const scrollToIndex = (
       index: number,
-      alignment: "start" | "center" | "end" = "start"
+      alignment: "start" | "center" | "end" = "start",
     ) => {
       // console.log(
       //   `[Scrolling] scrollToIndex called: index=${index}, alignment=${alignment}`
@@ -405,7 +413,7 @@ export const withScrolling = (config: ScrollingConfig = {}) => {
     const scrollToPage = (
       page: number,
       limit: number = 20,
-      alignment: "start" | "center" | "end" = "start"
+      alignment: "start" | "center" | "end" = "start",
     ) => {
       // Validate alignment parameter
       if (
@@ -413,7 +421,7 @@ export const withScrolling = (config: ScrollingConfig = {}) => {
         !["start", "center", "end"].includes(alignment)
       ) {
         console.warn(
-          `[Scrolling] Invalid alignment "${alignment}", using "start"`
+          `[Scrolling] Invalid alignment "${alignment}", using "start"`,
         );
         alignment = "start";
       }
@@ -427,7 +435,7 @@ export const withScrolling = (config: ScrollingConfig = {}) => {
         const collection = (component.viewport as any).collection;
         if (collection) {
           const highestLoadedPage = Math.floor(
-            collection.getLoadedRanges().size
+            collection.getLoadedRanges().size,
           );
 
           if (page > highestLoadedPage + 1) {
@@ -435,13 +443,13 @@ export const withScrolling = (config: ScrollingConfig = {}) => {
             const maxPagesToLoad = 10; // Reasonable limit
             const targetPage = Math.min(
               page,
-              highestLoadedPage + maxPagesToLoad
+              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}`
+                `Will load up to page ${targetPage}`,
             );
 
             // Trigger sequential loading to the target page (limited)
@@ -449,11 +457,11 @@ export const withScrolling = (config: ScrollingConfig = {}) => {
             const currentOffset = highestLoadedPage * limit;
 
             // Load pages sequentially up to the limited target
-            console.log(
-              `[Scrolling] Initiating sequential load from page ${
-                highestLoadedPage + 1
-              } to ${targetPage}`
-            );
+            // console.log(
+            //   `[Scrolling] Initiating sequential load from page ${
+            //     highestLoadedPage + 1
+            //   } to ${targetPage}`,
+            // );
 
             // Scroll to the last loaded position first
             const lastLoadedIndex = highestLoadedPage * limit;
@@ -479,7 +487,7 @@ export const withScrolling = (config: ScrollingConfig = {}) => {
     // Update scroll bounds
     const updateScrollBounds = (
       newTotalSize: number,
-      newContainerSize: number
+      newContainerSize: number,
     ) => {
       totalVirtualSize = newTotalSize;
       containerSize = newContainerSize;
@@ -489,6 +497,14 @@ export const withScrolling = (config: ScrollingConfig = {}) => {
         viewportState.containerSize = newContainerSize;
       }
 
+      // Don't clamp scroll position until we have real data loaded
+      // This prevents resetting initialScrollIndex position before data arrives
+      // Check totalItems instead of totalVirtualSize since virtualSize can be non-zero from padding
+      const totalItems = viewportState?.totalItems || 0;
+      if (totalItems <= 0) {
+        return;
+      }
+
       // Clamp current position to new bounds
       const maxScroll = Math.max(0, totalVirtualSize - containerSize);
       if (scrollPosition > maxScroll) {
@@ -500,7 +516,7 @@ export const withScrolling = (config: ScrollingConfig = {}) => {
     const originalScrollToIndex = component.viewport.scrollToIndex;
     component.viewport.scrollToIndex = (
       index: number,
-      alignment?: "start" | "center" | "end"
+      alignment?: "start" | "center" | "end",
     ) => {
       scrollToIndex(index, alignment);
       originalScrollToIndex?.(index, alignment);
@@ -510,7 +526,7 @@ export const withScrolling = (config: ScrollingConfig = {}) => {
     (component.viewport as any).scrollToPage = (
       page: number,
       limit?: number,
-      alignment?: "start" | "center" | "end"
+      alignment?: "start" | "center" | "end",
     ) => {
       scrollToPage(page, limit, alignment);
     };
@@ -562,7 +578,7 @@ export const withScrolling = (config: ScrollingConfig = {}) => {
         speedTracker = updateSpeedTracker(
           speedTracker,
           scrollPosition,
-          previousPosition
+          previousPosition,
         );
 
         // Update viewport state

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

@@ -13,12 +13,18 @@ import type { ViewportContext, ViewportComponent } from "../types";
  */
 export function wrapInitialize<T extends ViewportContext & ViewportComponent>(
   component: T,
-  featureInit: () => void
+  featureInit: () => void,
 ): void {
   const originalInitialize = component.viewport.initialize;
   component.viewport.initialize = () => {
-    originalInitialize();
-    featureInit();
+    // Check if already initialized (returns false if already done)
+    const result = originalInitialize();
+    // Only run feature init if base init actually ran (didn't return false)
+    if (result !== false) {
+      featureInit();
+    }
+    // Propagate the result through the chain so outer wrappers know to skip
+    return result;
   };
 }
 
@@ -28,7 +34,7 @@ export function wrapInitialize<T extends ViewportContext & ViewportComponent>(
  */
 export function wrapDestroy<T extends Record<string, any>>(
   component: T,
-  cleanup: () => void
+  cleanup: () => void,
 ): void {
   if ("destroy" in component && typeof component.destroy === "function") {
     const originalDestroy = component.destroy;
@@ -82,7 +88,7 @@ export function clamp(value: number, min: number, max: number): number {
 export function storeFeatureFunction<T extends Record<string, any>>(
   component: T,
   name: string,
-  fn: Function
+  fn: Function,
 ): void {
   (component as any)[name] = fn;
 }

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

@@ -13,6 +13,7 @@ export interface VirtualConfig {
   orientation?: "vertical" | "horizontal";
   autoDetectItemSize?: boolean;
   debug?: boolean;
+  initialScrollIndex?: number;
 }
 
 /**
@@ -29,6 +30,7 @@ export const withVirtual = (config: VirtualConfig = {}) => {
         ? VIEWPORT_CONSTANTS.VIRTUAL_SCROLL.AUTO_DETECT_ITEM_SIZE
         : false,
       debug = false,
+      initialScrollIndex = 0,
     } = config;
 
     // Use provided itemSize or default, but mark if we should auto-detect
@@ -38,6 +40,7 @@ export const withVirtual = (config: VirtualConfig = {}) => {
     const MAX_VIRTUAL_SIZE = VIEWPORT_CONSTANTS.VIRTUAL_SCROLL.MAX_VIRTUAL_SIZE;
     let viewportState: any;
     let hasCalculatedItemSize = false;
+    let hasRecalculatedScrollForCompression = false; // Track if we've recalculated scroll position for compression
 
     // Initialize using shared wrapper
     wrapInitialize(component, () => {
@@ -54,7 +57,32 @@ export const withVirtual = (config: VirtualConfig = {}) => {
       });
 
       updateTotalVirtualSize(viewportState.totalItems);
-      updateVisibleRange(viewportState.scrollPosition || 0);
+
+      // If we have an initial scroll index, calculate initial scroll position
+      // Note: We store the initialScrollIndex to use directly in range calculations
+      // because scroll position may be compressed for large lists
+      let initialScrollPosition = viewportState.scrollPosition || 0;
+
+      if (initialScrollIndex > 0) {
+        // Store the target index for use in range calculations
+        (viewportState as any).targetScrollIndex = initialScrollIndex;
+
+        // Calculate scroll position (may be compressed for large lists)
+        initialScrollPosition =
+          initialScrollIndex * (viewportState.itemSize || initialItemSize);
+        viewportState.scrollPosition = initialScrollPosition;
+
+        // Notify scrolling feature to sync its local scroll position
+        // Use setTimeout to ensure scrolling feature has initialized
+        setTimeout(() => {
+          component.emit?.("viewport:scroll-position-sync", {
+            position: initialScrollPosition,
+            source: "initial-scroll-index",
+          });
+        }, 0);
+      }
+
+      updateVisibleRange(initialScrollPosition);
 
       // Ensure container size is measured after DOM is ready
       requestAnimationFrame(() => {
@@ -75,7 +103,7 @@ export const withVirtual = (config: VirtualConfig = {}) => {
 
     // Calculate visible range
     const calculateVisibleRange = (
-      scrollPosition: number
+      scrollPosition: number,
     ): { start: number; end: number } => {
       if (!viewportState) {
         console.warn("[Virtual] No viewport state, returning empty range");
@@ -91,6 +119,17 @@ export const withVirtual = (config: VirtualConfig = {}) => {
         !totalItems ||
         totalItems <= 0
       ) {
+        // If we have an initialScrollIndex, use it to calculate the range
+        // even when totalItems is 0 (not yet loaded from API)
+        if (initialScrollIndex > 0) {
+          const visibleCount = Math.ceil(
+            (containerSize || 600) /
+              (viewportState.itemSize || initialItemSize),
+          );
+          const start = Math.max(0, initialScrollIndex - overscan);
+          const end = initialScrollIndex + visibleCount + overscan;
+          return { start, end };
+        }
         log(`Invalid state: container=${containerSize}, items=${totalItems}`);
         return { start: 0, end: 0 };
       }
@@ -102,12 +141,27 @@ export const withVirtual = (config: VirtualConfig = {}) => {
 
       let start: number, end: number;
 
+      // Check if we have a target scroll index (for initialScrollIndex with compression)
+      const targetScrollIndex = (viewportState as any).targetScrollIndex;
+
       if (compressionRatio < 1) {
         // Compressed space calculation
-        const scrollRatio = scrollPosition / virtualSize;
-        const exactIndex = scrollRatio * totalItems;
-        start = Math.floor(exactIndex);
-        end = Math.ceil(exactIndex) + visibleCount;
+        // If we have a targetScrollIndex, use it directly instead of calculating from scroll position
+        // This ensures we show the correct items even when virtual space is compressed
+        if (targetScrollIndex !== undefined && targetScrollIndex > 0) {
+          start = Math.max(0, targetScrollIndex - overscan);
+          end = Math.min(
+            totalItems - 1,
+            targetScrollIndex + visibleCount + overscan,
+          );
+          // Clear targetScrollIndex after first use so normal scrolling works
+          delete (viewportState as any).targetScrollIndex;
+        } else {
+          const scrollRatio = scrollPosition / virtualSize;
+          const exactIndex = scrollRatio * totalItems;
+          start = Math.floor(exactIndex);
+          end = Math.ceil(exactIndex) + visibleCount;
+        }
 
         // Near-bottom handling
         const maxScroll = virtualSize - containerSize;
@@ -115,16 +169,16 @@ export const withVirtual = (config: VirtualConfig = {}) => {
 
         if (distanceFromBottom <= containerSize && distanceFromBottom >= -1) {
           const itemsAtBottom = Math.floor(
-            containerSize / viewportState.itemSize
+            containerSize / viewportState.itemSize,
           );
           const firstVisibleAtBottom = Math.max(0, totalItems - itemsAtBottom);
           const interpolation = Math.max(
             0,
-            Math.min(1, 1 - distanceFromBottom / containerSize)
+            Math.min(1, 1 - distanceFromBottom / containerSize),
           );
 
           start = Math.floor(
-            start + (firstVisibleAtBottom - start) * interpolation
+            start + (firstVisibleAtBottom - start) * interpolation,
           );
           end =
             distanceFromBottom <= 1
@@ -148,7 +202,7 @@ export const withVirtual = (config: VirtualConfig = {}) => {
         // Direct calculation
         start = Math.max(
           0,
-          Math.floor(scrollPosition / viewportState.itemSize) - overscan
+          Math.floor(scrollPosition / viewportState.itemSize) - overscan,
         );
         end = Math.min(totalItems - 1, start + visibleCount + overscan * 2);
       }
@@ -179,12 +233,54 @@ export const withVirtual = (config: VirtualConfig = {}) => {
       return { start, end };
     };
 
+    // Calculate actual visible range (without overscan buffer)
+    const calculateActualVisibleRange = (scrollPosition: number) => {
+      if (!viewportState) return { start: 0, end: 0 };
+
+      const { containerSize, totalItems } = viewportState;
+      if (!containerSize || !totalItems) return { start: 0, end: 0 };
+
+      const itemSize = viewportState.itemSize;
+      const visibleCount = Math.ceil(containerSize / itemSize);
+      const compressionRatio = viewportState.virtualTotalSize
+        ? (totalItems * itemSize) / viewportState.virtualTotalSize
+        : 1;
+
+      let start: number, end: number;
+
+      if (compressionRatio < 1) {
+        // Compressed space - calculate based on scroll ratio
+        const virtualSize =
+          viewportState.virtualTotalSize || totalItems * itemSize;
+        const scrollRatio = scrollPosition / virtualSize;
+        start = Math.floor(scrollRatio * totalItems);
+        end = Math.min(totalItems - 1, start + visibleCount - 1);
+      } else {
+        // Direct calculation
+        start = Math.floor(scrollPosition / itemSize);
+        end = Math.min(totalItems - 1, start + visibleCount - 1);
+      }
+
+      // Ensure valid range
+      start = Math.max(0, start);
+      end = Math.max(start, end);
+
+      return { start, end };
+    };
+
     // Update functions
     const updateVisibleRange = (scrollPosition: number) => {
       if (!viewportState) return;
       viewportState.visibleRange = calculateVisibleRange(scrollPosition);
+
+      // DEBUG: Log who calls updateVisibleRange with 0 when it should be non-zero
+
+      // Calculate actual visible range (without overscan) for UI display
+      const actualVisibleRange = calculateActualVisibleRange(scrollPosition);
+
       component.emit?.("viewport:range-changed", {
         range: viewportState.visibleRange,
+        visibleRange: actualVisibleRange,
         scrollPosition,
       });
     };
@@ -201,7 +297,7 @@ export const withVirtual = (config: VirtualConfig = {}) => {
       let totalPadding = 0;
       if (viewportState.itemsContainer) {
         const computedStyle = window.getComputedStyle(
-          viewportState.itemsContainer
+          viewportState.itemsContainer,
         );
         const paddingTop = parseFloat(computedStyle.paddingTop) || 0;
         const paddingBottom = parseFloat(computedStyle.paddingBottom) || 0;
@@ -211,7 +307,7 @@ export const withVirtual = (config: VirtualConfig = {}) => {
       // Include padding in the virtual size
       viewportState.virtualTotalSize = Math.min(
         actualSize + totalPadding,
-        MAX_VIRTUAL_SIZE
+        MAX_VIRTUAL_SIZE,
       );
 
       // Strategic log for debugging gap issue
@@ -259,7 +355,7 @@ export const withVirtual = (config: VirtualConfig = {}) => {
 
     // Event listeners
     component.on?.("viewport:scroll", (data: any) =>
-      updateVisibleRange(data.position)
+      updateVisibleRange(data.position),
     );
 
     component.on?.("viewport:items-changed", (data: any) => {
@@ -270,20 +366,55 @@ export const withVirtual = (config: VirtualConfig = {}) => {
     });
 
     // Listen for total items changes (important for cursor pagination)
+    // Note: setTotalItems() updates viewportState.totalItems BEFORE emitting this event,
+    // so we can't rely on viewportState.totalItems to detect the first total.
+    // Instead we use the hasRecalculatedScrollForCompression flag.
     component.on?.("viewport:total-items-changed", (data: any) => {
+      if (data.total === undefined) return;
+
+      // FIX: When we first receive totalItems with initialScrollIndex and compression,
+      // recalculate scroll position to account for compression.
+      // Without this, initialScrollIndex calculates position as index * itemSize,
+      // but rendering uses compressed space, causing items to appear off-screen.
+      //
+      // We check this BEFORE updateTotalVirtualSize because we need to recalculate
+      // scroll position based on the new total, and the flag ensures we only do this once.
       if (
-        data.total !== undefined &&
-        data.total !== viewportState?.totalItems
+        initialScrollIndex > 0 &&
+        !hasRecalculatedScrollForCompression &&
+        data.total > 0
       ) {
-        log(
-          `Total items changed from ${viewportState?.totalItems} to ${data.total}`
-        );
-        updateTotalVirtualSize(data.total);
-        updateVisibleRange(viewportState?.scrollPosition || 0);
+        const actualTotalSize = data.total * viewportState.itemSize;
+        const isCompressed = actualTotalSize > MAX_VIRTUAL_SIZE;
+
+        if (isCompressed) {
+          // Recalculate scroll position using compression-aware formula
+          // Same formula used in scrollToIndex
+          const ratio = initialScrollIndex / data.total;
+          const compressedPosition = ratio * MAX_VIRTUAL_SIZE;
+
+          viewportState.scrollPosition = compressedPosition;
 
-        // Trigger a render to update the view
-        component.viewport?.renderItems?.();
+          // Notify scrolling feature to sync its local scroll position
+          component.emit?.("viewport:scroll-position-sync", {
+            position: compressedPosition,
+            source: "compression-recalculation",
+          });
+
+          // Clear targetScrollIndex since we've now correctly calculated the scroll position
+          // The normal compressed scrolling formula will now work correctly
+          delete (viewportState as any).targetScrollIndex;
+        }
+
+        // Mark as done even if not compressed - we only want to do this check once
+        hasRecalculatedScrollForCompression = true;
       }
+
+      updateTotalVirtualSize(data.total);
+      updateVisibleRange(viewportState?.scrollPosition || 0);
+
+      // Trigger a render to update the view
+      component.viewport?.renderItems?.();
     });
 
     // Listen for container size changes to recalculate virtual size
@@ -329,14 +460,24 @@ export const withVirtual = (config: VirtualConfig = {}) => {
 
           if (sizes.length > 0) {
             const avgSize = Math.round(
-              sizes.reduce((sum, size) => sum + size, 0) / sizes.length
+              sizes.reduce((sum, size) => sum + size, 0) / sizes.length,
             );
-
-            // console.log(
-            //   `[Virtual] Auto-detected item size: ${avgSize}px (was ${viewportState.itemSize}px), based on ${sizes.length} items`
-            // );
+            const previousItemSize = viewportState.itemSize;
             viewportState.itemSize = avgSize;
 
+            // If we have an initialScrollIndex, recalculate scroll position
+            // based on the newly detected item size
+            if (initialScrollIndex > 0 && avgSize !== previousItemSize) {
+              const newScrollPosition = initialScrollIndex * avgSize;
+              viewportState.scrollPosition = newScrollPosition;
+
+              // Notify scrolling feature to sync its local scroll position
+              component.emit?.("viewport:scroll-position-sync", {
+                position: newScrollPosition,
+                source: "item-size-detected",
+              });
+            }
+
             // Recalculate everything with new size
             updateTotalVirtualSize(viewportState.totalItems);
             updateVisibleRange(viewportState.scrollPosition || 0);
@@ -373,7 +514,7 @@ export const withVirtual = (config: VirtualConfig = {}) => {
       calculateIndexFromPosition: (position: number) =>
         Math.floor(
           position /
-            ((viewportState?.itemSize || initialItemSize) * compressionRatio)
+            ((viewportState?.itemSize || initialItemSize) * compressionRatio),
         ),
       calculatePositionForIndex: (index: number) =>
         index * (viewportState?.itemSize || initialItemSize) * compressionRatio,

package/src/core/viewport/types.ts

@@ -49,7 +49,7 @@ export interface ViewportConfig {
   // Template for rendering items
   template?: (
     item: any,
-    index: number
+    index: number,
   ) => string | HTMLElement | any[] | Record<string, any>;
 
   // Collection/data source configuration
@@ -109,7 +109,7 @@ export interface ViewportConfig {
 export interface ViewportComponent extends ViewportContext {
   viewport: {
     // Core API
-    initialize(): void;
+    initialize(): boolean | void;
     destroy(): void;
     updateViewport(): void;