@pdanpdan/virtual-scroll 0.4.0 → 0.6.0

package/src/components/VirtualScroll.vue

@@ -1,213 +1,33 @@
 <script setup lang="ts" generic="T">
+/**
+ * A high-performance virtual scrolling component for Vue 3.
+ * Supports large lists and grids by only rendering visible items and using coordinate scaling.
+ * Features include sticky headers/footers, RTL support, custom scrollbars, and scroll restoration.
+ */
 import type {
+  ItemSlotProps,
   RenderedItem,
   ScrollAlignment,
-  ScrollAlignmentOptions,
+  ScrollbarSlotProps,
   ScrollDetails,
+  ScrollToIndexOptions,
+  VirtualScrollbarProps,
+  VirtualScrollComponentProps,
   VirtualScrollProps,
 } from '../types';
 import type { VNodeChild } from 'vue';
 
-import { computed, nextTick, onMounted, onUnmounted, ref, watch } from 'vue';
+import { computed, nextTick, onMounted, onUnmounted, ref, toRefs, useId, watch } from 'vue';
 
 import {
-  DEFAULT_ITEM_SIZE,
   useVirtualScroll,
 } from '../composables/useVirtualScroll';
-import { isWindowLike } from '../utils/scroll';
-import { calculateItemStyle } from '../utils/virtual-scroll-logic';
-
-export interface Props<T = unknown> {
-  /**
-   * Array of items to be virtualized.
-   * Required.
-   */
-  items: T[];
-
-  /**
-   * Fixed size of each item (in pixels) or a function that returns the size of an item.
-   * Pass 0, null or undefined for dynamic size detection via ResizeObserver.
-   * @default 40
-   */
-  itemSize?: number | ((item: T, index: number) => number) | null;
-
-  /**
-   * Direction of the scroll.
-   * - 'vertical': Standard vertical list.
-   * - 'horizontal': Standard horizontal list.
-   * - 'both': Grid mode virtualizing both rows and columns.
-   * @default 'vertical'
-   */
-  direction?: 'vertical' | 'horizontal' | 'both';
-
-  /**
-   * Number of items to render before the visible viewport.
-   * Useful for smoother scrolling and keyboard navigation.
-   * @default 5
-   */
-  bufferBefore?: number;
-
-  /**
-   * Number of items to render after the visible viewport.
-   * @default 5
-   */
-  bufferAfter?: number;
-
-  /**
-   * The scrollable container element or window.
-   * If not provided, the host element (root of VirtualScroll) is used.
-   * @default hostRef
-   */
-  container?: HTMLElement | Window | null;
-
-  /**
-   * Range of items to render during Server-Side Rendering.
-   * When provided, these items will be rendered in-flow before hydration.
-   * @see SSRRange
-   */
-  ssrRange?: {
-    /** First row index to render. */
-    start: number;
-    /** Last row index to render (exclusive). */
-    end: number;
-    /** First column index to render (for grid mode). */
-    colStart?: number;
-    /** Last column index to render (exclusive, for grid mode). */
-    colEnd?: number;
-  };
-
-  /**
-   * Number of columns for bidirectional (grid) scroll.
-   * Only applicable when direction="both".
-   * @default 0
-   */
-  columnCount?: number;
-
-  /**
-   * Fixed width of columns (in pixels), an array of widths, or a function for column widths.
-   * Pass 0, null or undefined for dynamic width detection via ResizeObserver.
-   * Only applicable when direction="both".
-   * @default 100
-   */
-  columnWidth?: number | number[] | ((index: number) => number) | null;
-
-  /**
-   * The HTML tag to use for the root container.
-   * @default 'div'
-   */
-  containerTag?: string;
-
-  /**
-   * The HTML tag to use for the items wrapper.
-   * Useful for <table> integration (e.g. 'tbody').
-   * @default 'div'
-   */
-  wrapperTag?: string;
-
-  /**
-   * The HTML tag to use for each item.
-   * Useful for <table> integration (e.g. 'tr').
-   * @default 'div'
-   */
-  itemTag?: string;
-
-  /**
-   * Additional padding at the start of the scroll container (top or left).
-   * Can be a number (applied to current direction) or an object with x/y.
-   * @default 0
-   */
-  scrollPaddingStart?: number | { x?: number; y?: number; };
-
-  /**
-   * Additional padding at the end of the scroll container (bottom or right).
-   * @default 0
-   */
-  scrollPaddingEnd?: number | { x?: number; y?: number; };
-
-  /**
-   * Whether the content in the 'header' slot is sticky.
-   * If true, the header size is measured and accounted for in scroll padding.
-   * @default false
-   */
-  stickyHeader?: boolean;
-
-  /**
-   * Whether the content in the 'footer' slot is sticky.
-   * @default false
-   */
-  stickyFooter?: boolean;
+import { useVirtualScrollbar } from '../composables/useVirtualScrollbar';
+import { getPaddingX, getPaddingY } from '../utils/scroll';
+import { calculateItemStyle, displayToVirtual } from '../utils/virtual-scroll-logic';
+import VirtualScrollbar from './VirtualScrollbar.vue';
 
-  /**
-   * Gap between items in pixels (vertical gap in vertical/grid mode, horizontal gap in horizontal mode).
-   * @default 0
-   */
-  gap?: number;
-
-  /**
-   * Gap between columns in pixels. Only applicable when direction="both" or "horizontal".
-   * @default 0
-   */
-  columnGap?: number;
-
-  /**
-   * Indices of items that should stick to the top/start of the viewport.
-   * Supports iOS-style pushing effect where the next sticky item pushes the previous one.
-   * @default []
-   */
-  stickyIndices?: number[];
-
-  /**
-   * Distance from the end of the scrollable area (in pixels) to trigger the 'load' event.
-   * @default 200
-   */
-  loadDistance?: number;
-
-  /**
-   * Whether items are currently being loaded.
-   * Prevents multiple 'load' events from triggering and shows the 'loading' slot.
-   * @default false
-   */
-  loading?: boolean;
-
-  /**
-   * Whether to automatically restore and maintain scroll position when items are prepended to the list.
-   * Perfect for chat applications.
-   * @default false
-   */
-  restoreScrollOnPrepend?: boolean;
-
-  /**
-   * Initial scroll index to jump to immediately after mount.
-   */
-  initialScrollIndex?: number;
-
-  /**
-   * Alignment for the initial scroll index.
-   * @default 'start'
-   * @see ScrollAlignment
-   */
-  initialScrollAlign?: ScrollAlignment | ScrollAlignmentOptions;
-
-  /**
-   * Default size for items before they are measured by ResizeObserver.
-   * Only used when itemSize is dynamic.
-   * @default 40
-   */
-  defaultItemSize?: number;
-
-  /**
-   * Default width for columns before they are measured by ResizeObserver.
-   * Only used when columnWidth is dynamic.
-   * @default 100
-   */
-  defaultColumnWidth?: number;
-
-  /**
-   * Whether to show debug information (visible offsets and indices) over items.
-   * @default false
-   */
-  debug?: boolean;
-}
+export interface Props<T = unknown> extends VirtualScrollComponentProps<T> {}
 
 const props = withDefaults(defineProps<Props<T>>(), {
   direction: 'vertical',
@@ -228,6 +48,7 @@ const props = withDefaults(defineProps<Props<T>>(), {
   loading: false,
   restoreScrollOnPrepend: false,
   debug: false,
+  virtualScrollbar: false,
 });
 
 const emit = defineEmits<{
@@ -246,35 +67,7 @@ const slots = defineSlots<{
   /**
    * Scoped slot for rendering each individual item.
    */
-  item?: (props: {
-    /** The original data item from the `items` array. */
-    item: T;
-    /** The original index of the item in the `items` array. */
-    index: number;
-    /**
-     * Information about the current visible range of columns (for grid mode).
-     * @see ColumnRange
-     */
-    columnRange: {
-      /** Index of the first rendered column. */
-      start: number;
-      /** Index of the last rendered column (exclusive). */
-      end: number;
-      /** Pixel offset from the start of the row to the first rendered cell. */
-      padStart: number;
-      /** Pixel offset from the last rendered cell to the end of the row. */
-      padEnd: number;
-    };
-    /**
-     * Helper function to get the width of a specific column.
-     * Useful for setting consistent widths in grid mode.
-     */
-    getColumnWidth: (index: number) => number;
-    /** Whether this item is configured to be sticky via `stickyIndices`. */
-    isSticky?: boolean | undefined;
-    /** Whether this item is currently in a sticky state (stuck at the top/start). */
-    isStickyActive?: boolean | undefined;
-  }) => VNodeChild;
+  item?: (props: ItemSlotProps<T>) => VNodeChild;
 
   /**
    * Content shown at the end of the list when the `loading` prop is true.
@@ -287,6 +80,12 @@ const slots = defineSlots<{
    * Can be made sticky using the `stickyFooter` prop.
    */
   footer?: (props: Record<string, never>) => VNodeChild;
+
+  /**
+   * Scoped slot for rendering custom scrollbars.
+   * If provided, the default VirtualScrollbar is not rendered.
+   */
+  scrollbar?: (props: ScrollbarSlotProps) => VNodeChild;
 }>();
 
 const hostRef = ref<HTMLElement | null>(null);
@@ -295,60 +94,66 @@ const headerRef = ref<HTMLElement | null>(null);
 const footerRef = ref<HTMLElement | null>(null);
 const itemRefs = new Map<number, HTMLElement>();
 
+const instanceId = useId();
+
+/**
+ * Unique ID for the scrollable container.
+ * Used for accessibility (aria-controls) and to target the element in DOM.
+ */
+const containerId = computed(() => `vs-container-${ instanceId }`);
+
 const measuredPaddingStart = ref(0);
 const measuredPaddingEnd = ref(0);
 
+const effectiveContainer = computed(() => (props.container === undefined ? hostRef.value : props.container));
+
 const isHeaderFooterInsideContainer = computed(() => {
-  const container = props.container === undefined
-    ? hostRef.value
-    : props.container;
+  const container = effectiveContainer.value;
 
   return container === hostRef.value
     || (typeof window !== 'undefined' && (container === window || container === null));
 });
 
 const virtualScrollProps = computed(() => {
-  const pStart = props.scrollPaddingStart;
-  const pEnd = props.scrollPaddingEnd;
-
   /* Trigger re-evaluation on items array mutations */
   // eslint-disable-next-line ts/no-unused-expressions
   props.items.length;
 
-  const startX = typeof pStart === 'object'
-    ? (pStart.x || 0)
-    : ((props.direction === 'horizontal' || props.direction === 'both') ? (pStart || 0) : 0);
-  const startY = typeof pStart === 'object'
-    ? (pStart.y || 0)
-    : ((props.direction === 'vertical' || props.direction === 'both') ? (pStart || 0) : 0);
-
-  const endX = typeof pEnd === 'object'
-    ? (pEnd.x || 0)
-    : ((props.direction === 'horizontal' || props.direction === 'both') ? (pEnd || 0) : 0);
-  const endY = typeof pEnd === 'object'
-    ? (pEnd.y || 0)
-    : ((props.direction === 'vertical' || props.direction === 'both') ? (pEnd || 0) : 0);
-
   return {
     items: props.items,
     itemSize: props.itemSize,
     direction: props.direction,
     bufferBefore: props.bufferBefore,
     bufferAfter: props.bufferAfter,
-    container: props.container === undefined
-      ? hostRef.value
-      : props.container,
+    container: effectiveContainer.value,
     hostElement: wrapperRef.value,
+    hostRef: hostRef.value,
     ssrRange: props.ssrRange,
     columnCount: props.columnCount,
     columnWidth: props.columnWidth,
     scrollPaddingStart: {
-      x: startX,
-      y: startY + (props.stickyHeader && isHeaderFooterInsideContainer.value ? measuredPaddingStart.value : 0),
+      x: getPaddingX(props.scrollPaddingStart, props.direction),
+      y: getPaddingY(props.scrollPaddingStart, props.direction),
     },
     scrollPaddingEnd: {
-      x: endX,
-      y: endY + (props.stickyFooter && isHeaderFooterInsideContainer.value ? measuredPaddingEnd.value : 0),
+      x: getPaddingX(props.scrollPaddingEnd, props.direction),
+      y: getPaddingY(props.scrollPaddingEnd, props.direction),
+    },
+    flowPaddingStart: {
+      x: 0,
+      y: props.stickyHeader ? 0 : measuredPaddingStart.value,
+    },
+    flowPaddingEnd: {
+      x: 0,
+      y: props.stickyFooter ? 0 : measuredPaddingEnd.value,
+    },
+    stickyStart: {
+      x: 0,
+      y: props.stickyHeader && isHeaderFooterInsideContainer.value ? measuredPaddingStart.value : 0,
+    },
+    stickyEnd: {
+      x: 0,
+      y: props.stickyFooter && isHeaderFooterInsideContainer.value ? measuredPaddingEnd.value : 0,
     },
     gap: props.gap,
     columnGap: props.columnGap,
@@ -366,26 +171,102 @@ const virtualScrollProps = computed(() => {
 
 const {
   isHydrated,
+  isRtl,
   columnRange,
   renderedItems,
   scrollDetails,
-  totalHeight,
-  totalWidth,
+  renderedHeight,
+  renderedWidth,
   getColumnWidth,
+  getRowHeight,
   scrollToIndex,
   scrollToOffset,
   updateHostOffset,
   updateItemSizes,
+  updateDirection,
+  getItemOffset,
+  getRowOffset,
+  getColumnOffset,
+  getItemSize,
   refresh: coreRefresh,
   stopProgrammaticScroll,
+  scaleX,
+  scaleY,
+  isWindowContainer,
+  componentOffset,
+  renderedVirtualWidth,
+  renderedVirtualHeight,
 } = useVirtualScroll(virtualScrollProps);
 
+const useVirtualScrolling = computed(() => scaleX.value !== 1 || scaleY.value !== 1);
+
+const showVirtualScrollbars = computed(() => {
+  if (isWindowContainer.value) {
+    return false;
+  }
+  return props.virtualScrollbar === true || scaleX.value !== 1 || scaleY.value !== 1;
+});
+
+function handleVerticalScrollbarScrollToOffset(offset: number) {
+  const { displayViewportSize } = scrollDetails.value;
+  const scrollableRange = renderedHeight.value - displayViewportSize.height;
+  if (offset >= scrollableRange - 0.5) {
+    scrollToOffset(null, Number.POSITIVE_INFINITY);
+  } else {
+    const virtualOffset = displayToVirtual(offset, componentOffset.y, scaleY.value);
+    scrollToOffset(null, virtualOffset);
+  }
+}
+
+function handleHorizontalScrollbarScrollToOffset(offset: number) {
+  const { displayViewportSize } = scrollDetails.value;
+  const scrollableRange = renderedWidth.value - displayViewportSize.width;
+  if (offset >= scrollableRange - 0.5) {
+    scrollToOffset(Number.POSITIVE_INFINITY, null);
+  } else {
+    const virtualOffset = displayToVirtual(offset, componentOffset.x, scaleX.value);
+    scrollToOffset(virtualOffset, null);
+  }
+}
+
+const verticalScrollbar = useVirtualScrollbar({
+  axis: 'vertical',
+  totalSize: renderedHeight,
+  position: computed(() => scrollDetails.value.displayScrollOffset.y),
+  viewportSize: computed(() => 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),
+  scrollToOffset: handleHorizontalScrollbarScrollToOffset,
+  containerId,
+  isRtl,
+});
+
+const slotColumnRange = computed(() => {
+  if (props.direction !== 'both') {
+    return columnRange.value;
+  }
+  return {
+    ...columnRange.value,
+    padStart: 0,
+    padEnd: 0,
+  };
+});
+
 /**
  * Resets all dynamic measurements and re-initializes from props.
  * Also triggers manual re-measurement of all currently rendered items.
  */
 function refresh() {
   coreRefresh();
+  updateDirection();
   nextTick(() => {
     const updates: { index: number; inlineSize: number; blockSize: number; element?: HTMLElement; }[] = [];
 
@@ -408,13 +289,15 @@ function refresh() {
 
 // Watch for scroll details and emit event
 watch(scrollDetails, (details, oldDetails) => {
-  if (!isHydrated.value) {
+  if (!isHydrated.value || !details) {
     return;
   }
   emit('scroll', details);
 
   if (
     !oldDetails
+    || !oldDetails.range
+    || !oldDetails.columnRange
     || details.range.start !== oldDetails.range.start
     || details.range.end !== oldDetails.range.end
     || details.columnRange.start !== oldDetails.columnRange.start
@@ -433,14 +316,14 @@ watch(scrollDetails, (details, oldDetails) => {
   }
 
   // vertical or both
-  if (props.direction !== 'horizontal') {
+  if (props.direction !== 'horizontal' && details.totalSize) {
     const remaining = details.totalSize.height - (details.scrollOffset.y + details.viewportSize.height);
     if (remaining <= props.loadDistance) {
       emit('load', 'vertical');
     }
   }
   // horizontal or both
-  if (props.direction !== 'vertical') {
+  if (props.direction !== 'vertical' && details.totalSize) {
     const remaining = details.totalSize.width - (details.scrollOffset.x + details.viewportSize.width);
     if (remaining <= props.loadDistance) {
       emit('load', 'horizontal');
@@ -449,7 +332,7 @@ watch(scrollDetails, (details, oldDetails) => {
 });
 
 watch(isHydrated, (hydrated) => {
-  if (hydrated) {
+  if (hydrated && scrollDetails.value?.range && scrollDetails.value?.columnRange) {
     emit('visibleRangeChange', {
       start: scrollDetails.value.range.start,
       end: scrollDetails.value.range.end,
@@ -507,23 +390,21 @@ const extraResizeObserver = typeof window === 'undefined'
     updateHostOffset();
   });
 
-watch(headerRef, (newEl, oldEl) => {
-  if (oldEl) {
-    extraResizeObserver?.unobserve(oldEl);
-  }
-  if (newEl) {
-    extraResizeObserver?.observe(newEl);
-  }
-}, { immediate: true });
+function watchExtraRef(refEl: typeof headerRef, measuredValue: typeof measuredPaddingStart) {
+  watch(refEl, (newEl, oldEl) => {
+    if (oldEl) {
+      extraResizeObserver?.unobserve(oldEl);
+    }
+    if (newEl) {
+      extraResizeObserver?.observe(newEl);
+    } else {
+      measuredValue.value = 0;
+    }
+  }, { immediate: true });
+}
 
-watch(footerRef, (newEl, oldEl) => {
-  if (oldEl) {
-    extraResizeObserver?.unobserve(oldEl);
-  }
-  if (newEl) {
-    extraResizeObserver?.observe(newEl);
-  }
-}, { immediate: true });
+watchExtraRef(headerRef, measuredPaddingStart);
+watchExtraRef(footerRef, measuredPaddingEnd);
 
 onMounted(() => {
   if (hostRef.value) {
@@ -548,6 +429,22 @@ watch([ hostRef, wrapperRef ], ([ newHost ], [ oldHost ]) => {
   }
 });
 
+watch([ hostRef, useVirtualScrolling ], ([ host, virtual ], [ oldHost, oldVirtual ]) => {
+  const needsUpdate = host !== oldHost || virtual !== oldVirtual;
+  if (oldHost && needsUpdate) {
+    oldHost.removeEventListener('wheel', handleWheel);
+  }
+  if (host && needsUpdate) {
+    host.addEventListener('wheel', handleWheel, { passive: !virtual });
+  }
+}, { immediate: true });
+
+/**
+ * Callback ref to track and measure item elements.
+ *
+ * @param el - The element or null if unmounting.
+ * @param index - The original index of the item.
+ */
 function setItemRef(el: unknown, index: number) {
   if (el) {
     itemRefs.set(index, el as HTMLElement);
@@ -568,54 +465,342 @@ function setItemRef(el: unknown, index: number) {
   }
 }
 
+/**
+ * State for inertia scrolling
+ */
+const isPointerScrolling = ref(false);
+let startPointerPos = { x: 0, y: 0 };
+let startScrollOffset = { x: 0, y: 0 };
+let lastPointerPos = { x: 0, y: 0 };
+let lastPointerTime = 0;
+let velocity = { x: 0, y: 0 };
+let inertiaAnimationFrame: number | null = null;
+
+// Friction constant (0.9 to 0.98 is usually best)
+const FRICTION = 0.95;
+// Minimum velocity to continue the animation
+const MIN_VELOCITY = 0.1;
+
+/**
+ * Recursively animates the scroll offset based on velocity and friction.
+ */
+function startInertiaAnimation() {
+  const step = () => {
+    // Apply friction to the velocity
+    velocity.x *= FRICTION;
+    velocity.y *= FRICTION;
+
+    // Calculate the new scroll offset
+    const currentX = scrollDetails.value.scrollOffset.x;
+    const currentY = scrollDetails.value.scrollOffset.y;
+
+    // Move the scroll position by the current velocity
+    scrollToOffset(
+      currentX + velocity.x * 16, // Assuming ~60fps (16ms per frame)
+      currentY + velocity.y * 16,
+      { behavior: 'auto' },
+    );
+
+    // Continue animation if we haven't slowed down to a halt
+    if (Math.abs(velocity.x) > MIN_VELOCITY || Math.abs(velocity.y) > MIN_VELOCITY) {
+      inertiaAnimationFrame = requestAnimationFrame(step);
+    } else {
+      stopInertia();
+    }
+  };
+
+  inertiaAnimationFrame = requestAnimationFrame(step);
+}
+
+/**
+ * Stops any ongoing inertia animation
+ */
+function stopInertia() {
+  if (inertiaAnimationFrame !== null) {
+    cancelAnimationFrame(inertiaAnimationFrame);
+    inertiaAnimationFrame = null;
+  }
+  velocity = { x: 0, y: 0 };
+}
+
+/**
+ * Handles pointer down events on the container to start emulated scrolling when scaling is active.
+ *
+ * @param event - The pointer down event.
+ */
+function handlePointerDown(event: PointerEvent) {
+  stopProgrammaticScroll();
+  stopInertia(); // Stop any existing momentum
+
+  if (!useVirtualScrolling.value) {
+    return;
+  }
+
+  // Only handle primary button or touch
+  if (event.pointerType === 'mouse' && event.button !== 0) {
+    return;
+  }
+
+  isPointerScrolling.value = true;
+  startPointerPos = { x: event.clientX, y: event.clientY };
+  lastPointerPos = { x: event.clientX, y: event.clientY };
+  lastPointerTime = performance.now();
+  startScrollOffset = {
+    x: scrollDetails.value.scrollOffset.x,
+    y: scrollDetails.value.scrollOffset.y,
+  };
+
+  (event.currentTarget as HTMLElement).setPointerCapture(event.pointerId);
+}
+
+/**
+ * Handles pointer move events on the container to perform emulated scrolling.
+ *
+ * @param event - The pointer move event.
+ */
+function handlePointerMove(event: PointerEvent) {
+  if (!isPointerScrolling.value) {
+    return;
+  }
+
+  const now = performance.now();
+  const dt = now - lastPointerTime;
+
+  if (dt > 0) {
+    // Calculate instantaneous velocity (pixels per millisecond)
+    const instantVelocityX = (lastPointerPos.x - event.clientX) / dt;
+    const instantVelocityY = (lastPointerPos.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;
+  }
+
+  lastPointerPos = { x: event.clientX, y: event.clientY };
+  lastPointerTime = now;
+
+  const deltaX = startPointerPos.x - event.clientX;
+  const deltaY = startPointerPos.y - event.clientY;
+
+  requestAnimationFrame(() => {
+    scrollToOffset(
+      startScrollOffset.x + deltaX,
+      startScrollOffset.y + deltaY,
+      { behavior: 'auto' },
+    );
+  });
+}
+
+/**
+ * Handles pointer up and cancel events to end emulated scrolling.
+ *
+ * @param event - The pointer event.
+ */
+function handlePointerUp(event: PointerEvent) {
+  if (!isPointerScrolling.value) {
+    return;
+  }
+
+  isPointerScrolling.value = false;
+  (event.currentTarget as HTMLElement).releasePointerCapture(event.pointerId);
+
+  // If the user was moving fast enough, start the inertia loop
+  if (Math.abs(velocity.x) > MIN_VELOCITY || Math.abs(velocity.y) > MIN_VELOCITY) {
+    // avoid unwanted cross-axis drift
+    if (Math.abs(velocity.x) > 4 * Math.abs(velocity.y)) {
+      velocity.y = 0;
+    } else if (Math.abs(velocity.y) > 4 * Math.abs(velocity.x)) {
+      velocity.x = 0;
+    }
+
+    startInertiaAnimation();
+  }
+}
+
+/**
+ * Handles mouse wheel events to support high-precision scrolling for large content or virtual scrollbars.
+ *
+ * @param event - The wheel event.
+ */
+function handleWheel(event: WheelEvent) {
+  const { scrollOffset } = scrollDetails.value;
+  stopProgrammaticScroll();
+
+  if (useVirtualScrolling.value) {
+    // Prevent default browser scroll as we are handling it manually
+    event.preventDefault();
+
+    // For large content we manually scroll to keep precision/control
+    let deltaX = event.deltaX;
+    let deltaY = event.deltaY;
+
+    if (event.shiftKey && deltaX === 0) {
+      deltaX = deltaY;
+      deltaY = 0;
+    }
+
+    const targetX = scrollOffset.x + deltaX;
+    const targetY = scrollOffset.y + deltaY;
+
+    scrollToOffset(targetX, targetY, { behavior: 'auto' });
+  }
+}
+
+/**
+ * Handles keyboard events for navigation (Home, End, Arrows, PageUp/Down).
+ *
+ * @param event - The keyboard event.
+ */
 function handleKeyDown(event: KeyboardEvent) {
   const { viewportSize, scrollOffset } = scrollDetails.value;
   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; };
+
   switch (event.key) {
-    case 'Home':
+    case 'Home': {
       event.preventDefault();
       stopProgrammaticScroll();
-      scrollToIndex(0, 0, 'start');
+      const distance = Math.max(scrollOffset.x, scrollOffset.y);
+      const viewport = props.direction === 'horizontal' ? viewportSize.width : viewportSize.height;
+      const behavior = distance > 10 * viewport ? 'auto' : 'smooth';
+
+      scrollToIndex(0, 0, { behavior, align: 'start' });
       break;
+    }
     case 'End': {
       event.preventDefault();
       stopProgrammaticScroll();
       const lastItemIndex = props.items.length - 1;
       const lastColIndex = (props.columnCount || 0) > 0 ? props.columnCount - 1 : 0;
 
-      if (isHorizontal) {
-        if (isVertical) {
-          scrollToIndex(lastItemIndex, lastColIndex, 'end');
-        } else {
-          scrollToIndex(0, lastItemIndex, 'end');
-        }
+      const { totalSize } = scrollDetails.value;
+      const distance = Math.max(
+        totalSize.width - scrollOffset.x - viewportSize.width,
+        totalSize.height - scrollOffset.y - viewportSize.height,
+      );
+      const viewport = props.direction === 'horizontal' ? viewportSize.width : viewportSize.height;
+      const behavior = distance > 10 * viewport ? 'auto' : 'smooth';
+
+      if (props.direction === 'both') {
+        scrollToIndex(lastItemIndex, lastColIndex, { behavior, align: 'end' });
       } else {
-        scrollToIndex(lastItemIndex, 0, 'end');
+        scrollToIndex(
+          props.direction === 'vertical' ? lastItemIndex : 0,
+          props.direction === 'horizontal' ? lastItemIndex : 0,
+          { behavior, align: 'end' },
+        );
       }
       break;
     }
-    case 'ArrowUp':
+    case 'ArrowUp': {
       event.preventDefault();
       stopProgrammaticScroll();
-      scrollToOffset(null, scrollOffset.y - DEFAULT_ITEM_SIZE);
+      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' });
+      }
       break;
-    case 'ArrowDown':
+    }
+    case 'ArrowDown': {
       event.preventDefault();
       stopProgrammaticScroll();
-      scrollToOffset(null, scrollOffset.y + DEFAULT_ITEM_SIZE);
+      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' });
+      }
       break;
-    case 'ArrowLeft':
+    }
+    case 'ArrowLeft': {
       event.preventDefault();
       stopProgrammaticScroll();
-      scrollToOffset(scrollOffset.x - DEFAULT_ITEM_SIZE, null);
+      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' });
+        }
+      }
       break;
-    case 'ArrowRight':
+    }
+    case 'ArrowRight': {
       event.preventDefault();
       stopProgrammaticScroll();
-      scrollToOffset(scrollOffset.x + DEFAULT_ITEM_SIZE, null);
+      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' });
+          }
+        }
+      }
       break;
+    }
     case 'PageUp':
       event.preventDefault();
       stopProgrammaticScroll();
@@ -641,30 +826,121 @@ onUnmounted(() => {
   extraResizeObserver?.disconnect();
 });
 
-const isWindowContainer = computed(() => isWindowLike(props.container));
-
 const containerStyle = computed(() => {
+  const base: Record<string, string | number | undefined> = {
+    ...(props.direction !== 'vertical' ? { whiteSpace: 'nowrap' as const } : {}),
+  };
+
+  if (showVirtualScrollbars.value || !isWindowContainer.value) {
+    base.overflow = 'auto';
+  }
+
+  if (useVirtualScrolling.value) {
+    base.touchAction = 'none';
+  }
+
   if (isWindowContainer.value) {
-    return {
-      ...(props.direction !== 'vertical' ? { whiteSpace: 'nowrap' as const } : {}),
-    };
+    return base;
   }
 
   if (props.containerTag === 'table') {
     return {
+      ...base,
+      display: 'block',
       minInlineSize: props.direction === 'vertical' ? '100%' : 'auto',
     };
   }
 
+  return base;
+});
+
+const verticalScrollbarProps = computed<ScrollbarSlotProps | null>(() => {
+  if (props.direction === 'horizontal') {
+    return null;
+  }
+  const { displayViewportSize, displayScrollOffset } = scrollDetails.value;
+  if (renderedHeight.value <= displayViewportSize.height) {
+    return null;
+  }
+
+  const scrollbarProps: VirtualScrollbarProps = {
+    axis: 'vertical',
+    totalSize: renderedHeight.value,
+    position: displayScrollOffset.y,
+    viewportSize: displayViewportSize.height,
+    scrollToOffset: handleVerticalScrollbarScrollToOffset,
+    containerId: containerId.value,
+    isRtl: isRtl.value,
+  };
+
   return {
-    ...(props.direction !== 'vertical' ? { whiteSpace: 'nowrap' as const } : {}),
+    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,
   };
 });
 
-const wrapperStyle = computed(() => ({
-  inlineSize: props.direction === 'vertical' ? '100%' : `${ totalWidth.value }px`,
-  blockSize: props.direction === 'horizontal' ? '100%' : `${ totalHeight.value }px`,
-}));
+const horizontalScrollbarProps = computed<ScrollbarSlotProps | null>(() => {
+  if (props.direction === 'vertical') {
+    return null;
+  }
+  const { displayViewportSize, displayScrollOffset } = scrollDetails.value;
+  if (renderedWidth.value <= displayViewportSize.width) {
+    return null;
+  }
+
+  const scrollbarProps: VirtualScrollbarProps = {
+    axis: 'horizontal',
+    totalSize: renderedWidth.value,
+    position: displayScrollOffset.x,
+    viewportSize: displayViewportSize.width,
+    scrollToOffset: handleHorizontalScrollbarScrollToOffset,
+    containerId: containerId.value,
+    isRtl: isRtl.value,
+  };
+
+  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 wrapperStyle = computed(() => {
+  const isHorizontal = props.direction === 'horizontal';
+  const isVertical = props.direction === 'vertical';
+  const isBoth = props.direction === 'both';
+
+  const style: Record<string, string | number | undefined> = {
+    inlineSize: isVertical ? '100%' : `${ renderedVirtualWidth.value }px`,
+    blockSize: isHorizontal ? '100%' : `${ renderedVirtualHeight.value }px`,
+  };
+
+  if (!isHydrated.value) {
+    style.display = 'flex';
+    style.flexDirection = isHorizontal ? 'row' : 'column';
+    if ((isHorizontal || isBoth) && props.columnGap) {
+      style.columnGap = `${ props.columnGap }px`;
+    }
+    if ((isVertical || isBoth) && props.gap) {
+      style.rowGap = `${ props.gap }px`;
+    }
+  }
+
+  return style;
+});
 
 const loadingStyle = computed(() => {
   const isHorizontal = props.direction === 'horizontal';
@@ -676,20 +952,36 @@ const loadingStyle = computed(() => {
 });
 
 const spacerStyle = computed(() => ({
-  inlineSize: props.direction === 'vertical' ? '1px' : `${ totalWidth.value }px`,
-  blockSize: props.direction === 'horizontal' ? '1px' : `${ totalHeight.value }px`,
+  inlineSize: props.direction === 'vertical' ? '1px' : `${ renderedVirtualWidth.value }px`,
+  blockSize: props.direction === 'horizontal' ? '1px' : `${ renderedVirtualHeight.value }px`,
 }));
 
+/**
+ * Calculates the final style object for an item, including position and dimensions.
+ *
+ * @param item - The rendered item state.
+ * @returns CSS style object.
+ */
 function getItemStyle(item: RenderedItem<T>) {
-  return calculateItemStyle({
-    containerTag: props.containerTag,
+  const style = calculateItemStyle({
+    containerTag: props.containerTag || 'div',
     direction: props.direction,
     isHydrated: isHydrated.value,
     item,
     itemSize: props.itemSize,
     paddingStartX: (virtualScrollProps.value.scrollPaddingStart as { x: number; y: number; }).x,
     paddingStartY: (virtualScrollProps.value.scrollPaddingStart as { x: number; y: number; }).y,
+    isRtl: isRtl.value,
   });
+
+  if (!isHydrated.value && props.direction === 'both') {
+    style.display = 'flex';
+    if (props.columnGap) {
+      style.columnGap = `${ props.columnGap }px`;
+    }
+  }
+
+  return style;
 }
 
 const isDebug = computed(() => props.debug);
@@ -698,6 +990,8 @@ const headerTag = computed(() => isTable.value ? 'thead' : 'div');
 const footerTag = computed(() => isTable.value ? 'tfoot' : 'div');
 
 defineExpose({
+  ...toRefs(props),
+
   /**
    * Detailed information about the current scroll state.
    * @see ScrollDetails
@@ -719,6 +1013,41 @@ defineExpose({
    */
   getColumnWidth,
 
+  /**
+   * Helper to get the height of a specific row.
+   * @param index - The row index.
+   * @see useVirtualScroll
+   */
+  getRowHeight,
+
+  /**
+   * Helper to get the virtual offset of a specific row.
+   * @param index - The row index.
+   * @see useVirtualScroll
+   */
+  getRowOffset,
+
+  /**
+   * Helper to get the virtual offset of a specific column.
+   * @param index - The column index.
+   * @see useVirtualScroll
+   */
+  getColumnOffset,
+
+  /**
+   * Helper to get the virtual offset of a specific item.
+   * @param index - The item index.
+   * @see useVirtualScroll
+   */
+  getItemOffset,
+
+  /**
+   * Helper to get the size of a specific item along the scroll axis.
+   * @param index - The item index.
+   * @see useVirtualScroll
+   */
+  getItemSize,
+
   /**
    * Programmatically scroll to a specific row and/or column.
    *
@@ -751,13 +1080,69 @@ defineExpose({
    * Immediately stops any currently active smooth scroll animation and clears pending corrections.
    * @see useVirtualScroll
    */
-  stopProgrammaticScroll,
+  stopProgrammaticScroll: () => {
+    stopProgrammaticScroll();
+    stopInertia();
+  },
+
+  /**
+   * Detects the current direction (LTR/RTL) of the scroll container.
+   */
+  updateDirection,
+
+  /**
+   * Whether the scroll container is in Right-to-Left (RTL) mode.
+   */
+  isRtl,
+
+  /**
+   * Whether the component has finished its first client-side mount and hydration.
+   */
+  isHydrated,
+
+  /**
+   * Coordinate scaling factor for X axis.
+   */
+  scaleX,
+
+  /**
+   * Coordinate scaling factor for Y axis.
+   */
+  scaleY,
+
+  /**
+   * Physical width of the content in the DOM (clamped to browser limits).
+   */
+  renderedWidth,
+
+  /**
+   * Physical height of the content in the DOM (clamped to browser limits).
+   */
+  renderedHeight,
+
+  /**
+   * Absolute offset of the component within its container.
+   */
+  componentOffset,
+
+  /**
+   * Properties for the vertical scrollbar.
+   * Useful when building custom scrollbar interfaces.
+   */
+  scrollbarPropsVertical: verticalScrollbarProps,
+
+  /**
+   * Properties for the horizontal scrollbar.
+   * Useful when building custom scrollbar interfaces.
+   */
+  scrollbarPropsHorizontal: horizontalScrollbarProps,
 });
 </script>
 
 <template>
   <component
     :is="containerTag"
+    :id="containerId"
     ref="hostRef"
     class="virtual-scroll-container"
     :class="[
@@ -766,15 +1151,37 @@ defineExpose({
         'virtual-scroll--hydrated': isHydrated,
         'virtual-scroll--window': isWindowContainer,
         'virtual-scroll--table': isTable,
+        'virtual-scroll--hide-scrollbar': showVirtualScrollbars,
       },
     ]"
     :style="containerStyle"
     tabindex="0"
     @keydown="handleKeyDown"
-    @wheel.passive="stopProgrammaticScroll"
-    @pointerdown.passive="stopProgrammaticScroll"
-    @touchstart.passive="stopProgrammaticScroll"
+    @pointerdown="handlePointerDown"
+    @pointermove="handlePointerMove"
+    @pointerup="handlePointerUp"
+    @pointercancel="handlePointerUp"
   >
+    <div
+      v-if="showVirtualScrollbars"
+      class="virtual-scroll-scrollbar-container"
+    >
+      <div
+        class="virtual-scroll-scrollbar-viewport"
+        :style="{
+          'inlineSize': `${ scrollDetails.displayViewportSize.width }px`,
+          'blockSize': `${ scrollDetails.displayViewportSize.height }px`,
+          '--vsi-scrollbar-has-cross-gap': direction === 'both' ? 1 : 0,
+        }"
+      >
+        <slot v-if="slots.scrollbar && verticalScrollbarProps" name="scrollbar" v-bind="verticalScrollbarProps" />
+        <VirtualScrollbar v-else-if="verticalScrollbarProps" v-bind="verticalScrollbarProps.scrollbarProps" />
+
+        <slot v-if="slots.scrollbar && horizontalScrollbarProps" name="scrollbar" v-bind="horizontalScrollbarProps" />
+        <VirtualScrollbar v-else-if="horizontalScrollbarProps" v-bind="horizontalScrollbarProps.scrollbarProps" />
+      </div>
+    </div>
+
     <component
       :is="headerTag"
       v-if="slots.header"
@@ -818,11 +1225,17 @@ defineExpose({
           name="item"
           :item="renderedItem.item"
           :index="renderedItem.index"
-          :column-range="columnRange"
+          :column-range="slotColumnRange"
           :get-column-width="getColumnWidth"
+          :gap="props.gap"
+          :column-gap="props.columnGap"
           :is-sticky="renderedItem.isSticky"
           :is-sticky-active="renderedItem.isStickyActive"
+          :is-sticky-active-x="renderedItem.isStickyActiveX"
+          :is-sticky-active-y="renderedItem.isStickyActiveY"
+          :offset="renderedItem.offset"
         />
+
         <div v-if="isDebug" class="virtual-scroll-debug-info">
           #{{ renderedItem.index }} ({{ Math.round(renderedItem.offset.x) }}, {{ Math.round(renderedItem.offset.y) }})
         </div>
@@ -850,109 +1263,139 @@ defineExpose({
 </template>
 
 <style scoped>
-.virtual-scroll-container {
-  position: relative;
-  block-size: 100%;
-  inline-size: 100%;
-  outline-offset: 1px;
+@layer components {
+  .virtual-scroll-container {
+    position: relative;
+    block-size: 100%;
+    inline-size: 100%;
+    outline-offset: 1px;
+
+    &:not(.virtual-scroll--window) {
+      overflow: auto;
+      overscroll-behavior: contain;
+    }
 
-  &:not(.virtual-scroll--window) {
-    overflow: auto;
-    overscroll-behavior: contain;
-  }
+    &.virtual-scroll--table {
+      display: block;
+    }
 
-  &.virtual-scroll--table {
-    display: block;
-  }
-}
+    &.virtual-scroll--hide-scrollbar {
+      scrollbar-width: none;
+      -ms-overflow-style: none;
 
-.virtual-scroll--horizontal {
-  white-space: nowrap;
-}
+      &::-webkit-scrollbar {
+        display: none;
+      }
+    }
 
-.virtual-scroll-wrapper {
-  contain: layout;
-  position: relative;
+    &.virtual-scroll--horizontal,
+    &.virtual-scroll--both {
+      white-space: nowrap;
+    }
+  }
 
-  :where(.virtual-scroll--hydrated > & > .virtual-scroll-item) {
-    position: absolute;
+  .virtual-scroll-scrollbar-container {
+    position: sticky;
     inset-block-start: 0;
     inset-inline-start: 0;
+    inline-size: 100%;
+    block-size: 0;
+    z-index: 30;
+    pointer-events: none;
+    overflow: visible;
   }
-}
 
-.virtual-scroll-item {
-  display: grid;
-  box-sizing: border-box;
-  will-change: transform;
+  .virtual-scroll-scrollbar-viewport {
+    position: absolute;
+    inset-block-start: 0;
+    inset-inline-start: 0;
+    pointer-events: none;
+  }
 
-  &:where(.virtual-scroll--debug) {
-    outline: 1px dashed rgba(255, 0, 0, 0.5);
-    background-color: rgba(255, 0, 0, 0.05);
+  .virtual-scroll-wrapper {
+    contain: layout;
+    position: relative;
 
-    &:where(:hover) {
-      background-color: rgba(255, 0, 0, 0.1);
-      z-index: 100;
+    :where(.virtual-scroll--hydrated > & > .virtual-scroll-item) {
+      position: absolute;
+      inset-block-start: 0;
+      inset-inline-start: 0;
     }
   }
-}
 
-.virtual-scroll-debug-info {
-  position: absolute;
-  inset-block-start: 2px;
-  inset-inline-end: 2px;
-  background: rgba(0, 0, 0, 0.7);
-  color: white;
-  font-size: 10px;
-  padding: 2px 4px;
-  border-radius: 4px;
-  pointer-events: none;
-  z-index: 100;
-  font-family: monospace;
-}
+  .virtual-scroll-item {
+    display: grid;
+    box-sizing: border-box;
+    will-change: transform;
 
-.virtual-scroll-spacer {
-  pointer-events: none;
-}
+    &:where(.virtual-scroll--debug) {
+      outline: 1px dashed rgba(255, 0, 0, 0.5);
+      background-color: rgba(255, 0, 0, 0.05);
 
-.virtual-scroll-header,
-.virtual-scroll-footer {
-  position: relative;
-  z-index: 20;
-}
+      &:where(:hover) {
+        background-color: rgba(255, 0, 0, 0.1);
+        z-index: 100;
+      }
+    }
+  }
 
-.virtual-scroll--sticky {
-  position: sticky;
+  .virtual-scroll-debug-info {
+    position: absolute;
+    inset-block-start: 2px;
+    inset-inline-end: 2px;
+    background: rgba(0, 0, 0, 0.7);
+    color: white;
+    font-size: 10px;
+    padding: 2px 4px;
+    border-radius: 4px;
+    pointer-events: none;
+    z-index: 100;
+    font-family: monospace;
+  }
 
-  &:where(.virtual-scroll-header) {
-    inset-block-start: 0;
-    inset-inline-start: 0;
-    min-inline-size: 100%;
-    box-sizing: border-box;
+  .virtual-scroll-spacer {
+    pointer-events: none;
   }
 
-  &:where(.virtual-scroll-footer) {
-    inset-block-end: 0;
-    inset-inline-start: 0;
-    min-inline-size: 100%;
-    box-sizing: border-box;
+  .virtual-scroll-header,
+  .virtual-scroll-footer {
+    position: relative;
+    z-index: 20;
   }
 
-  &:where(.virtual-scroll-item) {
-    z-index: 10;
+  .virtual-scroll--sticky {
+    position: sticky;
+
+    &:where(.virtual-scroll-header) {
+      inset-block-start: 0;
+      inset-inline-start: 0;
+      min-inline-size: 100%;
+      box-sizing: border-box;
+    }
+
+    &:where(.virtual-scroll-footer) {
+      inset-block-end: 0;
+      inset-inline-start: 0;
+      min-inline-size: 100%;
+      box-sizing: border-box;
+    }
+
+    &:where(.virtual-scroll-item) {
+      z-index: 10;
+    }
   }
-}
 
-:is(tbody.virtual-scroll-wrapper, thead.virtual-scroll-header, tfoot.virtual-scroll-footer) {
-  display: inline-flex;
-  min-inline-size: 100%;
-  & > :deep(tr) {
+  :is(tbody.virtual-scroll-wrapper, thead.virtual-scroll-header, tfoot.virtual-scroll-footer) {
     display: inline-flex;
     min-inline-size: 100%;
+    & > :deep(tr) {
+      display: inline-flex;
+      min-inline-size: 100%;
 
-    & > :is(td, th) {
-      display: inline-block;
-      align-items: center;
+      & > :is(td, th) {
+        display: inline-block;
+        align-items: center;
+      }
     }
   }
 }