@pdanpdan/virtual-scroll 0.10.0 → 0.10.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pdanpdan/virtual-scroll",
   "type": "module",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "A high-performance virtual scroll component for Vue 3",
   "author": "",
   "license": "MIT",

package/src/composables/useVirtualScroll.ts

@@ -6,6 +6,7 @@ import type {
   ScrollDetails,
   ScrollDirection,
   ScrollToIndexOptions,
+  ScrollToIndexResult,
   VirtualScrollProps,
 } from '../types';
 /* global ScrollToOptions */
@@ -112,10 +113,10 @@ export function useVirtualScroll<T = unknown>(
     pendingScroll.value = null;
   };
 
-  /** Previous internal horizontal virtual position. */
-  let lastInternalX = 0;
-  /** Previous internal vertical virtual position. */
-  let lastInternalY = 0;
+  /** Horizontal virtual scroll position at the start of the current scroll interaction (VU). */
+  let scrollStartX = 0;
+  /** Vertical virtual scroll position at the start of the current scroll interaction (VU). */
+  let scrollStartY = 0;
 
   // --- Computed Config ---
   /** Validated scroll direction. */
@@ -348,10 +349,9 @@ export function useVirtualScroll<T = unknown>(
     rowIndex?: number | null,
     colIndex?: number | null,
     options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions,
-  ) {
-    const isCorrection = (typeof options === 'object' && options !== null && 'isCorrection' in options)
-      ? options.isCorrection
-      : false;
+  ): ScrollToIndexResult {
+    const isCorrection = isScrollToIndexOptions(options) ? options.isCorrection : false;
+    const dryRun = isScrollToIndexOptions(options) ? options.dryRun : false;
 
     const container = props.value.container || window;
 
@@ -393,7 +393,7 @@ export function useVirtualScroll<T = unknown>(
       paddingEndY: paddingEndY.value,
     });
 
-    if (!isCorrection) {
+    if (!isCorrection && !dryRun) {
       const behavior = isScrollToIndexOptions(options) ? options.behavior : undefined;
       pendingScroll.value = {
         rowIndex,
@@ -416,14 +416,18 @@ export function useVirtualScroll<T = unknown>(
     }
     const scrollBehavior = isCorrection ? 'auto' : (behavior || 'smooth');
 
-    isProgrammaticScroll.value = true;
-    clearTimeout(programmaticScrollTimer);
-    if (scrollBehavior === 'smooth') {
-      programmaticScrollTimer = setTimeout(() => {
-        isProgrammaticScroll.value = false;
-        programmaticScrollTimer = undefined;
-        checkPendingScroll();
-      }, 500);
+    if (!dryRun) {
+      if (scrollBehavior === 'smooth' || !isCorrection) {
+        isProgrammaticScroll.value = true;
+        clearTimeout(programmaticScrollTimer);
+        if (scrollBehavior === 'smooth') {
+          programmaticScrollTimer = setTimeout(() => {
+            isProgrammaticScroll.value = false;
+            programmaticScrollTimer = undefined;
+            checkPendingScroll();
+          }, 1000);
+        }
+      }
     }
 
     const scrollOptions: ScrollToOptions = { behavior: scrollBehavior };
@@ -433,9 +437,12 @@ export function useVirtualScroll<T = unknown>(
     if (rowIndex !== null && rowIndex !== undefined) {
       scrollOptions.top = Math.max(0, finalY);
     }
-    scrollTo(container, scrollOptions);
 
-    if (scrollBehavior === 'auto' || scrollBehavior === undefined) {
+    if (!isCorrection && !dryRun) {
+      scrollTo(container, scrollOptions);
+    }
+
+    if (!dryRun && (scrollBehavior === 'auto' || scrollBehavior === undefined)) {
       if (colIndex !== null && colIndex !== undefined) {
         scrollX.value = (isRtl.value ? finalX : Math.max(0, finalX));
         internalScrollX.value = targetX;
@@ -445,6 +452,8 @@ export function useVirtualScroll<T = unknown>(
         internalScrollY.value = targetY;
       }
     }
+
+    return { targetX, targetY, displayTargetX, displayTargetY };
   }
 
   function scrollToOffset(x?: number | null, y?: number | null, options?: { behavior?: 'auto' | 'smooth'; }) {
@@ -456,7 +465,7 @@ export function useVirtualScroll<T = unknown>(
         isProgrammaticScroll.value = false;
         programmaticScrollTimer = undefined;
         checkPendingScroll();
-      }, 500);
+      }, 1000);
     }
     pendingScroll.value = null;
 
@@ -759,14 +768,23 @@ export function useVirtualScroll<T = unknown>(
     const scrollValueX = isRtl.value ? Math.abs(scrollX.value) : scrollX.value;
     const virtualX = displayToVirtual(scrollValueX, componentOffset.x, scaleX.value);
     const virtualY = displayToVirtual(scrollY.value, componentOffset.y, scaleY.value);
-    if (Math.abs(virtualX - lastInternalX) > 0.5) {
-      scrollDirectionX.value = virtualX > lastInternalX ? 'end' : 'start';
-      lastInternalX = virtualX;
-    }
-    if (Math.abs(virtualY - lastInternalY) > 0.5) {
-      scrollDirectionY.value = virtualY > lastInternalY ? 'end' : 'start';
-      lastInternalY = virtualY;
+
+    if (!isProgrammaticScroll.value) {
+      if (!isScrolling.value) {
+        scrollStartX = internalScrollX.value;
+        scrollStartY = internalScrollY.value;
+      }
+      const deltaX = virtualX - scrollStartX;
+      const deltaY = virtualY - scrollStartY;
+
+      if (Math.abs(deltaX) > 0.5) {
+        scrollDirectionX.value = deltaX > 0 ? 'end' : 'start';
+      }
+      if (Math.abs(deltaY) > 0.5) {
+        scrollDirectionY.value = deltaY > 0 ? 'end' : 'start';
+      }
     }
+
     internalScrollX.value = virtualX;
     internalScrollY.value = virtualY;
     if (!isProgrammaticScroll.value) {
@@ -1085,5 +1103,7 @@ export function useVirtualScroll<T = unknown>(
     getRowIndexAt,
     /** Helper to get the column index at a specific virtual offset (VU). */
     getColIndexAt,
+    /** @internal */
+    __internalState: ctx.internalState,
   };
 }

package/src/extensions/index.ts

@@ -1,4 +1,4 @@
-import type { RenderedItem, ScrollAlignment, ScrollAlignmentOptions, ScrollDetails, ScrollToIndexOptions, Size, VirtualScrollProps } from '../types';
+import type { RenderedItem, ScrollAlignment, ScrollAlignmentOptions, ScrollDetails, ScrollToIndexOptions, ScrollToIndexResult, Size, VirtualScrollProps } from '../types';
 import type { Ref } from 'vue';
 
 /**
@@ -51,7 +51,7 @@ export interface ExtensionContext<T = unknown> {
   /** Direct access to core component methods. */
   methods: {
     /** Scroll to a specific row and/or column. */
-    scrollToIndex: (rowIndex?: number | null, colIndex?: number | null, options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions) => void;
+    scrollToIndex: (rowIndex?: number | null, colIndex?: number | null, options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions) => ScrollToIndexResult;
     /** Scroll to a specific virtual pixel offset. */
     scrollToOffset: (x?: number | null, y?: number | null, options?: { behavior?: 'auto' | 'smooth'; }) => void;
     /** Detect and update text direction. */

package/src/extensions/snapping.ts

@@ -72,10 +72,23 @@ export function useSnappingExtension<T = unknown>(): VirtualScrollExtension<T> {
       }
 
       if (shouldSnap) {
-        ctx.methods.scrollToIndex(targetRow, targetCol, {
+        const { targetX, targetY } = ctx.methods.scrollToIndex(targetRow, targetCol, {
           align: { x: alignX, y: alignY },
-          behavior: 'smooth',
+          dryRun: true,
         });
+
+        const currentX = ctx.internalState.internalScrollX.value;
+        const currentY = ctx.internalState.internalScrollY.value;
+
+        const diffX = (targetCol !== null) ? Math.abs(targetX - currentX) : 0;
+        const diffY = (targetRow !== null) ? Math.abs(targetY - currentY) : 0;
+
+        if (diffX > 0.5 || diffY > 0.5) {
+          ctx.methods.scrollToIndex(targetRow, targetCol, {
+            align: { x: alignX, y: alignY },
+            behavior: 'smooth',
+          });
+        }
       }
     },
   };

package/src/types.ts

@@ -87,6 +87,25 @@ export interface ScrollToIndexOptions {
    * @internal
    */
   isCorrection?: boolean;
+
+  /**
+   * If true, only calculates the target position without performing the actual scroll.
+   * Useful for extensions that need to validate if a snap is necessary.
+   * @default false
+   */
+  dryRun?: boolean;
+}
+
+/** Result of the `scrollToIndex` method. */
+export interface ScrollToIndexResult {
+  /** Target relative horizontal position in virtual units (VU). */
+  targetX: number;
+  /** Target relative vertical position in virtual units (VU). */
+  targetY: number;
+  /** Target display horizontal position (DU). */
+  displayTargetX: number;
+  /** Target display vertical position (DU). */
+  displayTargetY: number;
 }
 
 /** Represents an item currently rendered in the virtual scroll area. */
@@ -566,7 +585,7 @@ export interface VirtualScrollInstance<T = unknown> extends VirtualScrollCompone
   /** The tag used for rendering items. */
   itemTag: string;
   /** Programmatically scroll to a specific row and/or column. */
-  scrollToIndex: (rowIndex?: number | null, colIndex?: number | null, options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions) => void;
+  scrollToIndex: (rowIndex?: number | null, colIndex?: number | null, options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions) => ScrollToIndexResult;
   /** Programmatically scroll to a specific pixel offset. */
   scrollToOffset: (x?: number | null, y?: number | null, options?: { behavior?: 'auto' | 'smooth'; }) => void;
   /** Resets all dynamic measurements and re-initializes from props. */

package/src/utils/scroll.ts

@@ -95,7 +95,7 @@ export function scrollTo(container: HTMLElement | Window | null | undefined, opt
  * @returns `true` if the options object contains scroll-to-index specific properties.
  */
 export function isScrollToIndexOptions(options: unknown): options is ScrollToIndexOptions {
-  return typeof options === 'object' && options != null && ('align' in options || 'behavior' in options || 'isCorrection' in options);
+  return typeof options === 'object' && options != null && ('align' in options || 'behavior' in options || 'isCorrection' in options || 'dryRun' in options);
 }
 
 /**

package/src/utils/virtual-scroll-logic.ts

@@ -1190,35 +1190,44 @@ export function resolveSnap(
   }
 
   if (mode === 'next') {
-    if (dir === 'start') {
-      effectiveMode = 'end';
-    } else if (dir === 'end') {
-      effectiveMode = 'start';
-    } else {
-      return null;
-    }
-
-    if (effectiveMode === 'start') {
-      // Scrolling towards end (dir === 'end') -> snap to NEXT item start
+    if (dir === 'end') {
+      // Scrolling items UP (towards end of list) -> snap to NEXT item start
       const size = getSize(currentIdx);
       if (size > viewSize) {
         return null;
       }
+      const scrolledOut = relScroll - getQuery(currentIdx);
+      const threshold = Math.min(5, size * 0.1);
+      if (scrolledOut <= threshold) {
+        return {
+          index: currentIdx,
+          align: 'start' as const,
+        };
+      }
       return {
         index: Math.min(count - 1, currentIdx + 1),
         align: 'start' as const,
       };
-    }
-    if (effectiveMode === 'end') {
-      // Scrolling towards start (dir === 'start') -> snap to PREVIOUS item end
+    } else if (dir === 'start') {
+      // Scrolling items DOWN (towards start of list) -> snap to PREVIOUS item end
       const size = getSize(currentEndIdx);
       if (size > viewSize) {
         return null;
       }
+      const scrolledOutBottom = (getQuery(currentEndIdx) + size) - (relScroll + viewSize);
+      const threshold = Math.min(5, size * 0.1);
+      if (scrolledOutBottom <= threshold) {
+        return {
+          index: currentEndIdx,
+          align: 'end' as const,
+        };
+      }
       return {
         index: Math.max(0, currentEndIdx - 1),
         align: 'end' as const,
       };
+    } else {
+      return null;
     }
   }