@pdanpdan/virtual-scroll 0.7.0 → 0.9.0

package/src/components/VirtualScroll.vue

@@ -11,7 +11,6 @@ import type {
   ScrollbarSlotProps,
   ScrollDetails,
   ScrollToIndexOptions,
-  VirtualScrollbarProps,
   VirtualScrollComponentProps,
   VirtualScrollProps,
 } from '../types';
@@ -23,8 +22,13 @@ import {
   useVirtualScroll,
 } from '../composables/useVirtualScroll';
 import { useVirtualScrollbar } from '../composables/useVirtualScrollbar';
-import { getPaddingX, getPaddingY } from '../utils/scroll';
-import { calculateItemStyle, displayToVirtual } from '../utils/virtual-scroll-logic';
+import { getPaddingX, getPaddingY, isWindowLike } from '../utils/scroll';
+import {
+  calculateInertiaStep,
+  calculateInstantaneousVelocity,
+  calculateItemStyle,
+  displayToVirtual,
+} from '../utils/virtual-scroll-logic';
 import VirtualScrollbar from './VirtualScrollbar.vue';
 
 export interface Props<T = unknown> extends VirtualScrollComponentProps<T> {}
@@ -110,9 +114,7 @@ const effectiveContainer = computed(() => (props.container === undefined ? hostR
 
 const isHeaderFooterInsideContainer = computed(() => {
   const container = effectiveContainer.value;
-
-  return container === hostRef.value
-    || (typeof window !== 'undefined' && (container === window || container === null));
+  return container === hostRef.value || isWindowLike(container);
 });
 
 const virtualScrollProps = computed(() => {
@@ -167,6 +169,7 @@ const virtualScrollProps = computed(() => {
     defaultItemSize: props.defaultItemSize,
     defaultColumnWidth: props.defaultColumnWidth,
     debug: props.debug,
+    snap: props.snap,
   } as VirtualScrollProps<T>;
 });
 
@@ -197,6 +200,8 @@ const {
   componentOffset,
   renderedVirtualWidth,
   renderedVirtualHeight,
+  getRowIndexAt,
+  getColIndexAt,
 } = useVirtualScroll(virtualScrollProps);
 
 const useVirtualScrolling = computed(() => scaleX.value !== 1 || scaleY.value !== 1);
@@ -230,25 +235,25 @@ function handleHorizontalScrollbarScrollToOffset(offset: number) {
   }
 }
 
-const verticalScrollbar = useVirtualScrollbar({
-  axis: 'vertical',
-  totalSize: renderedHeight,
-  position: computed(() => scrollDetails.value.displayScrollOffset.y),
-  viewportSize: computed(() => scrollDetails.value.displayViewportSize.height),
+const verticalScrollbar = useVirtualScrollbar(computed(() => ({
+  axis: 'vertical' as const,
+  totalSize: renderedHeight.value,
+  position: scrollDetails.value.displayScrollOffset.y,
+  viewportSize: scrollDetails.value.displayViewportSize.height,
   scrollToOffset: handleVerticalScrollbarScrollToOffset,
-  containerId,
-  isRtl,
-});
-
-const horizontalScrollbar = useVirtualScrollbar({
-  axis: 'horizontal',
-  totalSize: renderedWidth,
-  position: computed(() => scrollDetails.value.displayScrollOffset.x),
-  viewportSize: computed(() => scrollDetails.value.displayViewportSize.width),
+  containerId: containerId.value,
+  isRtl: isRtl.value,
+})));
+
+const horizontalScrollbar = useVirtualScrollbar(computed(() => ({
+  axis: 'horizontal' as const,
+  totalSize: renderedWidth.value,
+  position: scrollDetails.value.displayScrollOffset.x,
+  viewportSize: scrollDetails.value.displayViewportSize.width,
   scrollToOffset: handleHorizontalScrollbarScrollToOffset,
-  containerId,
-  isRtl,
-});
+  containerId: containerId.value,
+  isRtl: isRtl.value,
+})));
 
 const slotColumnRange = computed(() => {
   if (props.direction !== 'both') {
@@ -414,10 +419,7 @@ onMounted(() => {
 
   // Re-observe items that were set before observer was ready
   for (const el of itemRefs.values()) {
-    itemResizeObserver?.observe(el);
-    if (props.direction === 'both') {
-      el.querySelectorAll('[data-col-index]').forEach((c) => itemResizeObserver?.observe(c));
-    }
+    observeItem(el, true);
   }
 });
 
@@ -440,6 +442,20 @@ watch([ hostRef, useVirtualScrolling ], ([ host, virtual ], [ oldHost, oldVirtua
   }
 }, { immediate: true });
 
+/**
+ * Helper to manage ResizeObserver for an item and its optional cells.
+ *
+ * @param el - The item element.
+ * @param isObserve - True to observe, false to unobserve.
+ */
+function observeItem(el: HTMLElement, isObserve: boolean) {
+  const method = isObserve ? 'observe' : 'unobserve';
+  itemResizeObserver?.[ method ](el);
+  if (props.direction === 'both' && el.children.length > 0) {
+    el.querySelectorAll('[data-col-index]').forEach((c) => itemResizeObserver?.[ method ](c));
+  }
+}
+
 /**
  * Callback ref to track and measure item elements.
  *
@@ -448,19 +464,13 @@ watch([ hostRef, useVirtualScrolling ], ([ host, virtual ], [ oldHost, oldVirtua
  */
 function setItemRef(el: unknown, index: number) {
   if (el) {
-    itemRefs.set(index, el as HTMLElement);
-    itemResizeObserver?.observe(el as HTMLElement);
-
-    if (props.direction === 'both') {
-      (el as HTMLElement).querySelectorAll('[data-col-index]').forEach((c) => itemResizeObserver?.observe(c));
-    }
+    const htmlEl = el as HTMLElement;
+    itemRefs.set(index, htmlEl);
+    observeItem(htmlEl, true);
   } else {
     const oldEl = itemRefs.get(index);
     if (oldEl) {
-      itemResizeObserver?.unobserve(oldEl);
-      if (props.direction === 'both') {
-        oldEl.querySelectorAll('[data-col-index]').forEach((c) => itemResizeObserver?.unobserve(c));
-      }
+      observeItem(oldEl, false);
       itemRefs.delete(index);
     }
   }
@@ -487,18 +497,17 @@ const MIN_VELOCITY = 0.1;
  */
 function startInertiaAnimation() {
   const step = () => {
-    // Apply friction to the velocity
-    velocity.x *= FRICTION;
-    velocity.y *= FRICTION;
+    const { nextVelocity, delta } = calculateInertiaStep(velocity, FRICTION);
+    velocity.x = nextVelocity.x;
+    velocity.y = nextVelocity.y;
 
     // Calculate the new scroll offset
-    const currentX = scrollDetails.value.scrollOffset.x;
-    const currentY = scrollDetails.value.scrollOffset.y;
+    const { x: currentX, y: currentY } = scrollDetails.value.scrollOffset;
 
     // Move the scroll position by the current velocity
     scrollToOffset(
-      currentX + velocity.x * 16, // Assuming ~60fps (16ms per frame)
-      currentY + velocity.y * 16,
+      currentX + delta.x,
+      currentY + delta.y,
       { behavior: 'auto' },
     );
 
@@ -569,12 +578,11 @@ function handlePointerMove(event: PointerEvent) {
 
   if (dt > 0) {
     // Calculate instantaneous velocity (pixels per millisecond)
-    const instantVelocityX = (lastPointerPos.x - event.clientX) / dt;
-    const instantVelocityY = (lastPointerPos.y - event.clientY) / dt;
+    const instantVelocity = calculateInstantaneousVelocity(lastPointerPos, { x: event.clientX, y: event.clientY }, dt);
 
     // Use a moving average for smoother velocity tracking
-    velocity.x = velocity.x * 0.2 + instantVelocityX * 0.8;
-    velocity.y = velocity.y * 0.2 + instantVelocityY * 0.8;
+    velocity.x = velocity.x * 0.2 + instantVelocity.x * 0.8;
+    velocity.y = velocity.y * 0.2 + instantVelocity.y * 0.8;
   }
 
   lastPointerPos = { x: event.clientX, y: event.clientY };
@@ -632,18 +640,14 @@ function handleWheel(event: WheelEvent) {
     event.preventDefault();
 
     // For large content we manually scroll to keep precision/control
-    let deltaX = event.deltaX;
-    let deltaY = event.deltaY;
+    let { deltaX, deltaY } = event;
 
     if (event.shiftKey && deltaX === 0) {
       deltaX = deltaY;
       deltaY = 0;
     }
 
-    const targetX = scrollOffset.x + deltaX;
-    const targetY = scrollOffset.y + deltaY;
-
-    scrollToOffset(targetX, targetY, { behavior: 'auto' });
+    scrollToOffset(scrollOffset.x + deltaX, scrollOffset.y + deltaY, { behavior: 'auto' });
   }
 }
 
@@ -657,8 +661,149 @@ function handleKeyDown(event: KeyboardEvent) {
   const isHorizontal = props.direction !== 'vertical';
   const isVertical = props.direction !== 'horizontal';
 
-  const sStart = virtualScrollProps.value.stickyStart as { x: number; y: number; };
-  const sEnd = virtualScrollProps.value.stickyEnd as { x: number; y: number; };
+  const vProps = virtualScrollProps.value;
+  const sStart = vProps.stickyStart as { x: number; y: number; };
+  const sEnd = vProps.stickyEnd as { x: number; y: number; };
+  const pStart = vProps.scrollPaddingStart as { x: number; y: number; };
+  const pEnd = vProps.scrollPaddingEnd as { x: number; y: number; };
+
+  const snapModeProp = props.snap === true ? 'auto' : props.snap;
+  const snapMode = (snapModeProp && snapModeProp !== 'auto')
+    ? snapModeProp as 'start' | 'center' | 'end'
+    : null;
+
+  /**
+   * Helper to find center index.
+   */
+  const getCenterIndex = (isX: boolean) => {
+    const centerPos = (isX ? scrollOffset.x : scrollOffset.y) + (isX ? viewportSize.width : viewportSize.height) / 2;
+    return isX ? getColIndexAt(centerPos) : getRowIndexAt(centerPos);
+  };
+
+  const { currentIndex, currentEndIndex, currentColIndex, currentEndColIndex } = scrollDetails.value;
+
+  /**
+   * Helper to calculate the target index for PageUp/PageDown.
+   *
+   * @param isVerticalAxis - True for vertical, false for horizontal.
+   * @param isForward - True for forward (PageDown), false for backward (PageUp).
+   */
+  const getPageTarget = (isVerticalAxis: boolean, isForward: boolean) => {
+    const isHorizontalAxis = !isVerticalAxis;
+    const startIdx = isVerticalAxis ? currentIndex : currentColIndex;
+    const endIdx = isVerticalAxis ? currentEndIndex : currentEndColIndex;
+    const pageSize = Math.max(1, endIdx - startIdx);
+    const maxIdx = isVerticalAxis
+      ? props.items.length - 1
+      : (props.columnCount ? props.columnCount - 1 : props.items.length - 1);
+
+    if (isForward) {
+      if (snapMode === 'center') {
+        return Math.min(maxIdx, getCenterIndex(isHorizontalAxis) + pageSize);
+      }
+      if (snapMode === 'end') {
+        return Math.min(maxIdx, endIdx + pageSize);
+      }
+      return endIdx; // default or snapMode === 'start'
+    } else {
+      // backward
+      if (snapMode === 'center') {
+        return Math.max(0, getCenterIndex(isHorizontalAxis) - pageSize);
+      }
+      if (snapMode === 'start') {
+        return Math.max(0, startIdx - pageSize);
+      }
+      return startIdx; // default or snapMode === 'end'
+    }
+  };
+
+  /**
+   * Performs keyboard navigation for arrow keys.
+   *
+   * @param isVerticalAxis - True for vertical, false for horizontal.
+   * @param isForward - True for forward direction (Down/Right), false for backward.
+   */
+  const navigate = (isVerticalAxis: boolean, isForward: boolean) => {
+    const isHorizontalAxis = !isVerticalAxis;
+
+    if (snapMode === 'center') {
+      const centerIdx = getCenterIndex(isHorizontalAxis);
+      const maxIdx = isHorizontalAxis
+        ? (props.columnCount ? props.columnCount - 1 : props.items.length - 1)
+        : props.items.length - 1;
+      const targetIdx = isForward ? Math.min(maxIdx, centerIdx + 1) : Math.max(0, centerIdx - 1);
+      scrollToIndex(isVerticalAxis ? targetIdx : null, isHorizontalAxis ? targetIdx : null, { align: 'center' });
+      return;
+    }
+
+    if (isVerticalAxis) {
+      if (isForward) {
+        if (snapMode === 'start') {
+          scrollToIndex(Math.min(props.items.length - 1, currentIndex + 1), null, { align: 'start' });
+        } else {
+          const align = snapMode || 'end';
+          const viewportBottom = scrollOffset.y + viewportSize.height - (sEnd.y + pEnd.y);
+          const itemBottom = getRowOffset(currentEndIndex) + getRowHeight(currentEndIndex);
+
+          if (itemBottom > viewportBottom + 1) {
+            scrollToIndex(currentEndIndex, null, { align });
+          } else if (currentEndIndex < props.items.length - 1) {
+            scrollToIndex(currentEndIndex + 1, null, { align });
+          }
+        }
+      } else {
+        // backward
+        if (snapMode === 'end') {
+          scrollToIndex(Math.max(0, currentEndIndex - 1), null, { align: 'end' });
+        } else {
+          const align = snapMode || 'start';
+          const viewportTop = scrollOffset.y + sStart.y + pStart.y;
+          const itemPos = getRowOffset(currentIndex);
+
+          if (itemPos < viewportTop - 1) {
+            scrollToIndex(currentIndex, null, { align });
+          } else if (currentIndex > 0) {
+            scrollToIndex(currentIndex - 1, null, { align });
+          }
+        }
+      }
+    } else {
+      // Horizontal axis
+      const maxColIdx = props.columnCount ? props.columnCount - 1 : props.items.length - 1;
+      const isLogicalForward = isRtl.value ? !isForward : isForward;
+
+      if (isLogicalForward) {
+        if (snapMode === 'start') {
+          scrollToIndex(null, Math.min(maxColIdx, currentColIndex + 1), { align: 'start' });
+        } else {
+          const align = snapMode || 'end';
+          const viewportRight = scrollOffset.x + viewportSize.width - (sEnd.x + pEnd.x);
+          const colEndPos = (props.columnCount ? getColumnOffset(currentEndColIndex) + getColumnWidth(currentEndColIndex) : getItemOffset(currentEndColIndex) + getItemSize(currentEndColIndex));
+
+          if (colEndPos > viewportRight + 1) {
+            scrollToIndex(null, currentEndColIndex, { align });
+          } else if (currentEndColIndex < maxColIdx) {
+            scrollToIndex(null, currentEndColIndex + 1, { align });
+          }
+        }
+      } else {
+        // backward
+        if (snapMode === 'end') {
+          scrollToIndex(null, Math.max(0, currentEndColIndex - 1), { align: 'end' });
+        } else {
+          const align = snapMode || 'start';
+          const viewportLeft = scrollOffset.x + sStart.x + pStart.x;
+          const colStartPos = (props.columnCount ? getColumnOffset(currentColIndex) : getItemOffset(currentColIndex));
+
+          if (colStartPos < viewportLeft - 1) {
+            scrollToIndex(null, currentColIndex, { align });
+          } else if (currentColIndex > 0) {
+            scrollToIndex(null, currentColIndex - 1, { align });
+          }
+        }
+      }
+    }
+  };
 
   switch (event.key) {
     case 'Home': {
@@ -696,127 +841,51 @@ function handleKeyDown(event: KeyboardEvent) {
       }
       break;
     }
-    case 'ArrowUp': {
+    case 'ArrowUp':
       event.preventDefault();
       stopProgrammaticScroll();
-      if (!isVertical) {
-        return;
-      }
-
-      const { currentIndex, scrollOffset } = scrollDetails.value;
-      const viewportTop = scrollOffset.y + sStart.y + (virtualScrollProps.value.scrollPaddingStart as { x: number; y: number; }).y;
-      const itemPos = getRowOffset(currentIndex);
-
-      if (itemPos < viewportTop - 1) {
-        scrollToIndex(currentIndex, null, { align: 'start' });
-      } else if (currentIndex > 0) {
-        scrollToIndex(currentIndex - 1, null, { align: 'start' });
+      if (isVertical) {
+        navigate(true, false);
       }
       break;
-    }
-    case 'ArrowDown': {
+    case 'ArrowDown':
       event.preventDefault();
       stopProgrammaticScroll();
-      if (!isVertical) {
-        return;
-      }
-
-      const { currentEndIndex } = scrollDetails.value;
-      const viewportBottom = scrollOffset.y + viewportSize.height - (sEnd.y + (virtualScrollProps.value.scrollPaddingEnd as { x: number; y: number; }).y);
-      const itemBottom = getRowOffset(currentEndIndex) + getRowHeight(currentEndIndex);
-
-      if (itemBottom > viewportBottom + 1) {
-        scrollToIndex(currentEndIndex, null, { align: 'end' });
-      } else if (currentEndIndex < props.items.length - 1) {
-        scrollToIndex(currentEndIndex + 1, null, { align: 'end' });
+      if (isVertical) {
+        navigate(true, true);
       }
       break;
-    }
-    case 'ArrowLeft': {
+    case 'ArrowLeft':
       event.preventDefault();
       stopProgrammaticScroll();
-      if (!isHorizontal) {
-        return;
-      }
-
-      const { currentColIndex, currentEndColIndex } = scrollDetails.value;
-
-      if (isRtl.value) {
-        // RTL ArrowLeft -> towards logical END (Left)
-        const viewportLeft = scrollOffset.x + viewportSize.width - (sEnd.x + (virtualScrollProps.value.scrollPaddingEnd as { x: number; y: number; }).x);
-        const colEndPos = (props.columnCount ? getColumnOffset(currentEndColIndex) + getColumnWidth(currentEndColIndex) : getItemOffset(currentEndColIndex) + getItemSize(currentEndColIndex));
-
-        if (colEndPos > viewportLeft + 1) {
-          scrollToIndex(null, currentEndColIndex, { align: 'end' });
-        } else {
-          const maxColIdx = props.columnCount ? props.columnCount - 1 : props.items.length - 1;
-          if (currentEndColIndex < maxColIdx) {
-            scrollToIndex(null, currentEndColIndex + 1, { align: 'end' });
-          }
-        }
-      } else {
-        // LTR ArrowLeft -> towards logical START (Left)
-        const viewportLeft = scrollOffset.x + sStart.x + (virtualScrollProps.value.scrollPaddingStart as { x: number; y: number; }).x;
-        const colStartPos = (props.columnCount ? getColumnOffset(currentColIndex) : getItemOffset(currentColIndex));
-
-        if (colStartPos < viewportLeft - 1) {
-          scrollToIndex(null, currentColIndex, { align: 'start' });
-        } else if (currentColIndex > 0) {
-          scrollToIndex(null, currentColIndex - 1, { align: 'start' });
-        }
+      if (isHorizontal) {
+        navigate(false, false);
       }
       break;
-    }
-    case 'ArrowRight': {
+    case 'ArrowRight':
       event.preventDefault();
       stopProgrammaticScroll();
-      if (!isHorizontal) {
-        return;
-      }
-
-      const { currentColIndex, currentEndColIndex } = scrollDetails.value;
-
-      if (isRtl.value) {
-        // RTL ArrowRight -> towards logical START (Right)
-        const viewportRight = scrollOffset.x + sStart.x + (virtualScrollProps.value.scrollPaddingStart as { x: number; y: number; }).x;
-        const colStartPos = (props.columnCount ? getColumnOffset(currentColIndex) : getItemOffset(currentColIndex));
-
-        if (colStartPos < viewportRight - 1) {
-          scrollToIndex(null, currentColIndex, { align: 'start' });
-        } else if (currentColIndex > 0) {
-          scrollToIndex(null, currentColIndex - 1, { align: 'start' });
-        }
-      } else {
-        // LTR ArrowRight -> towards logical END (Right)
-        const viewportRight = scrollOffset.x + viewportSize.width - (sEnd.x + (virtualScrollProps.value.scrollPaddingEnd as { x: number; y: number; }).x);
-        const colEndPos = (props.columnCount ? getColumnOffset(currentEndColIndex) + getColumnWidth(currentEndColIndex) : getItemOffset(currentEndColIndex) + getItemSize(currentEndColIndex));
-
-        if (colEndPos > viewportRight + 1) {
-          scrollToIndex(null, currentEndColIndex, { align: 'end' });
-        } else {
-          const maxColIdx = props.columnCount ? props.columnCount - 1 : props.items.length - 1;
-          if (currentEndColIndex < maxColIdx) {
-            scrollToIndex(null, currentEndColIndex + 1, { align: 'end' });
-          }
-        }
+      if (isHorizontal) {
+        navigate(false, true);
       }
       break;
-    }
     case 'PageUp':
       event.preventDefault();
       stopProgrammaticScroll();
-      scrollToOffset(
-        !isVertical && isHorizontal ? scrollOffset.x - viewportSize.width : null,
-        isVertical ? scrollOffset.y - viewportSize.height : null,
-      );
+      if (props.direction === 'horizontal') {
+        scrollToIndex(null, getPageTarget(false, false), { align: snapMode || 'end' });
+      } else {
+        scrollToIndex(getPageTarget(true, false), null, { align: snapMode || 'end' });
+      }
       break;
     case 'PageDown':
       event.preventDefault();
       stopProgrammaticScroll();
-      scrollToOffset(
-        !isVertical && isHorizontal ? scrollOffset.x + viewportSize.width : null,
-        isVertical ? scrollOffset.y + viewportSize.height : null,
-      );
+      if (props.direction === 'horizontal') {
+        scrollToIndex(null, getPageTarget(false, true), { align: snapMode || 'start' });
+      } else {
+        scrollToIndex(getPageTarget(true, true), null, { align: snapMode || 'start' });
+      }
       break;
   }
 }
@@ -855,70 +924,79 @@ const containerStyle = computed(() => {
   return base;
 });
 
-const verticalScrollbarProps = computed<ScrollbarSlotProps | null>(() => {
-  if (props.direction === 'horizontal') {
-    return null;
-  }
-  const { displayViewportSize, displayScrollOffset } = scrollDetails.value;
-  if (renderedHeight.value <= displayViewportSize.height) {
+/**
+ * Internal helper to generate consistent ScrollbarSlotProps.
+ *
+ * @param axis - The scroll axis.
+ * @param totalSize - Total scrollable size (DU).
+ * @param position - Current scroll position (DU).
+ * @param viewportSize - Current viewport size (DU).
+ * @param scrollToOffsetCallback - Callback to perform scroll.
+ * @param scrollbar - Scrollbar state from useVirtualScrollbar.
+ * @returns Props for the scrollbar slot or null if content fits.
+ */
+function getScrollbarSlotProps(
+  axis: 'vertical' | 'horizontal',
+  totalSize: number,
+  position: number,
+  viewportSize: number,
+  scrollToOffsetCallback: (offset: number) => void,
+  scrollbar: ReturnType<typeof useVirtualScrollbar>,
+): ScrollbarSlotProps | null {
+  if (totalSize <= viewportSize) {
     return null;
   }
 
-  const scrollbarProps: VirtualScrollbarProps = {
-    axis: 'vertical',
-    totalSize: renderedHeight.value,
-    position: displayScrollOffset.y,
-    viewportSize: displayViewportSize.height,
-    scrollToOffset: handleVerticalScrollbarScrollToOffset,
-    containerId: containerId.value,
-    isRtl: isRtl.value,
-    ariaLabel: 'Vertical scroll',
-  };
-
   return {
-    axis: 'vertical',
-    positionPercent: verticalScrollbar.positionPercent.value,
-    viewportPercent: verticalScrollbar.viewportPercent.value,
-    thumbSizePercent: verticalScrollbar.thumbSizePercent.value,
-    thumbPositionPercent: verticalScrollbar.thumbPositionPercent.value,
-    trackProps: verticalScrollbar.trackProps.value,
-    thumbProps: verticalScrollbar.thumbProps.value,
-    scrollbarProps,
-    isDragging: verticalScrollbar.isDragging.value,
+    axis,
+    positionPercent: scrollbar.positionPercent.value,
+    viewportPercent: scrollbar.viewportPercent.value,
+    thumbSizePercent: scrollbar.thumbSizePercent.value,
+    thumbPositionPercent: scrollbar.thumbPositionPercent.value,
+    trackProps: scrollbar.trackProps.value,
+    thumbProps: scrollbar.thumbProps.value,
+    scrollbarProps: {
+      axis,
+      totalSize,
+      position,
+      viewportSize,
+      scrollToOffset: scrollToOffsetCallback,
+      containerId: containerId.value,
+      isRtl: isRtl.value,
+      ariaLabel: `${ axis === 'vertical' ? 'Vertical' : 'Horizontal' } scroll`,
+    },
+    isDragging: scrollbar.isDragging.value,
   };
-});
+}
 
-const horizontalScrollbarProps = computed<ScrollbarSlotProps | null>(() => {
-  if (props.direction === 'vertical') {
+const verticalScrollbarProps = computed(() => {
+  if (props.direction === 'horizontal') {
     return null;
   }
   const { displayViewportSize, displayScrollOffset } = scrollDetails.value;
-  if (renderedWidth.value <= displayViewportSize.width) {
+  return getScrollbarSlotProps(
+    'vertical',
+    renderedHeight.value,
+    displayScrollOffset.y,
+    displayViewportSize.height,
+    handleVerticalScrollbarScrollToOffset,
+    verticalScrollbar,
+  );
+});
+
+const horizontalScrollbarProps = computed(() => {
+  if (props.direction === 'vertical') {
     return null;
   }
-
-  const scrollbarProps: VirtualScrollbarProps = {
-    axis: 'horizontal',
-    totalSize: renderedWidth.value,
-    position: displayScrollOffset.x,
-    viewportSize: displayViewportSize.width,
-    scrollToOffset: handleHorizontalScrollbarScrollToOffset,
-    containerId: containerId.value,
-    isRtl: isRtl.value,
-    ariaLabel: 'Horizontal scroll',
-  };
-
-  return {
-    axis: 'horizontal',
-    positionPercent: horizontalScrollbar.positionPercent.value,
-    viewportPercent: horizontalScrollbar.viewportPercent.value,
-    thumbSizePercent: horizontalScrollbar.thumbSizePercent.value,
-    thumbPositionPercent: horizontalScrollbar.thumbPositionPercent.value,
-    trackProps: horizontalScrollbar.trackProps.value,
-    thumbProps: horizontalScrollbar.thumbProps.value,
-    scrollbarProps,
-    isDragging: horizontalScrollbar.isDragging.value,
-  };
+  const { displayViewportSize, displayScrollOffset } = scrollDetails.value;
+  return getScrollbarSlotProps(
+    'horizontal',
+    renderedWidth.value,
+    displayScrollOffset.x,
+    displayViewportSize.width,
+    handleHorizontalScrollbarScrollToOffset,
+    horizontalScrollbar,
+  );
 });
 
 const wrapperStyle = computed(() => {
@@ -1169,11 +1247,25 @@ defineExpose({
    */
   getItemSize,
 
+  /**
+   * Helper to get the row (or item) index at a specific vertical (or horizontal in horizontal mode) virtual offset (VU).
+   * @param offset - The virtual pixel offset.
+   * @see useVirtualScroll
+   */
+  getRowIndexAt,
+
+  /**
+   * Helper to get the column index at a specific horizontal virtual offset (VU).
+   * @param offset - The virtual pixel offset.
+   * @see useVirtualScroll
+   */
+  getColIndexAt,
+
   /**
    * Programmatically scroll to a specific row and/or column.
    *
-   * @param rowIndex - The row index to scroll to. Pass null to only scroll horizontally.
-   * @param colIndex - The column index to scroll to. Pass null to only scroll vertically.
+   * @param rowIndex - The row index to scroll to. Pass null to only scroll horizontally. Optional.
+   * @param colIndex - The column index to scroll to. Pass null to only scroll vertically. Optional.
    * @param options - Alignment and behavior options. Defaults to { align: 'auto', behavior: 'auto' }.
    * @see ScrollAlignment
    * @see ScrollToIndexOptions