@pdanpdan/virtual-scroll 0.5.0 → 0.6.0

package/dist/virtual-scroll.css

@@ -1 +1,2 @@
-@layer components{.virtual-scrollbar-track{--vsi-scrollbar-bg: var(--vs-scrollbar-bg, rgba(230, 230, 230, .9));--vsi-scrollbar-thumb-bg: var(--vs-scrollbar-thumb-bg, rgba(0, 0, 0, .3));--vsi-scrollbar-thumb-hover-bg: var(--vs-scrollbar-thumb-hover-bg, rgba(0, 0, 0, .6));--vsi-scrollbar-bg: var(--vs-scrollbar-bg, light-dark(rgba(230, 230, 230, .9), rgba(30, 30, 30, .9)));--vsi-scrollbar-thumb-bg: var(--vs-scrollbar-thumb-bg, light-dark(rgba(0, 0, 0, .3), rgba(255, 255, 255, .3)));--vsi-scrollbar-thumb-hover-bg: var(--vs-scrollbar-thumb-hover-bg, light-dark(rgba(0, 0, 0, .6), rgba(255, 255, 255, .6)));--vsi-scrollbar-radius: var(--vs-scrollbar-radius, 4px);--vsi-scrollbar-size: var(--vs-scrollbar-size, 8px);position:absolute;contain:layout;background-color:var(--vsi-scrollbar-bg);border-radius:var(--vsi-scrollbar-radius);z-index:30;transition:opacity .2s;user-select:none;-webkit-user-select:none;pointer-events:auto}.virtual-scrollbar-track.virtual-scrollbar-track--vertical{inline-size:var(--vsi-scrollbar-size);inset-block-start:2px;inset-inline-end:2px}.virtual-scrollbar-track.virtual-scrollbar-track--horizontal{block-size:var(--vsi-scrollbar-size);inset-inline-start:2px;inset-block-end:2px}.virtual-scrollbar-thumb{position:absolute;background-color:var(--vsi-scrollbar-thumb-bg);border-radius:var(--vsi-scrollbar-radius);touch-action:none;pointer-events:auto;cursor:pointer}.virtual-scrollbar-thumb:hover,.virtual-scrollbar-thumb:active,.virtual-scrollbar-thumb.virtual-scrollbar-thumb--active{background-color:var(--vsi-scrollbar-thumb-hover-bg)}.virtual-scrollbar-thumb.virtual-scrollbar-thumb--vertical{inline-size:100%}.virtual-scrollbar-thumb.virtual-scrollbar-thumb--horizontal{block-size:100%}}@layer components{.virtual-scroll-container[data-v-91b6ab6c]{position:relative;block-size:100%;inline-size:100%;outline-offset:1px}.virtual-scroll-container[data-v-91b6ab6c]:not(.virtual-scroll--window){overflow:auto;overscroll-behavior:contain}.virtual-scroll-container.virtual-scroll--table[data-v-91b6ab6c]{display:block}.virtual-scroll-container.virtual-scroll--hide-scrollbar[data-v-91b6ab6c]{scrollbar-width:none;-ms-overflow-style:none}.virtual-scroll-container.virtual-scroll--hide-scrollbar[data-v-91b6ab6c]::-webkit-scrollbar{display:none}.virtual-scroll-container.virtual-scroll--horizontal[data-v-91b6ab6c],.virtual-scroll-container.virtual-scroll--both[data-v-91b6ab6c]{white-space:nowrap}.virtual-scroll-scrollbar-container[data-v-91b6ab6c]{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-scrollbar-viewport[data-v-91b6ab6c]{position:absolute;inset-block-start:0;inset-inline-start:0;pointer-events:none}.virtual-scroll-wrapper[data-v-91b6ab6c]{contain:layout;position:relative}:where(.virtual-scroll--hydrated>.virtual-scroll-wrapper>.virtual-scroll-item[data-v-91b6ab6c]){position:absolute;inset-block-start:0;inset-inline-start:0}.virtual-scroll-item[data-v-91b6ab6c]{display:grid;box-sizing:border-box;will-change:transform}.virtual-scroll-item:where(.virtual-scroll--debug)[data-v-91b6ab6c]{outline:1px dashed rgba(255,0,0,.5);background-color:#ff00000d}.virtual-scroll-item:where(.virtual-scroll--debug)[data-v-91b6ab6c]:where(:hover){background-color:#ff00001a;z-index:100}.virtual-scroll-debug-info[data-v-91b6ab6c]{position:absolute;inset-block-start:2px;inset-inline-end:2px;background:#000000b3;color:#fff;font-size:10px;padding:2px 4px;border-radius:4px;pointer-events:none;z-index:100;font-family:monospace}.virtual-scroll-spacer[data-v-91b6ab6c]{pointer-events:none}.virtual-scroll-header[data-v-91b6ab6c],.virtual-scroll-footer[data-v-91b6ab6c]{position:relative;z-index:20}.virtual-scroll--sticky[data-v-91b6ab6c]{position:sticky}.virtual-scroll--sticky[data-v-91b6ab6c]:where(.virtual-scroll-header){inset-block-start:0;inset-inline-start:0;min-inline-size:100%;box-sizing:border-box}.virtual-scroll--sticky[data-v-91b6ab6c]:where(.virtual-scroll-footer){inset-block-end:0;inset-inline-start:0;min-inline-size:100%;box-sizing:border-box}.virtual-scroll--sticky[data-v-91b6ab6c]:where(.virtual-scroll-item){z-index:10}:is(tbody.virtual-scroll-wrapper,thead.virtual-scroll-header,tfoot.virtual-scroll-footer)[data-v-91b6ab6c]{display:inline-flex;min-inline-size:100%}:is(tbody.virtual-scroll-wrapper,thead.virtual-scroll-header,tfoot.virtual-scroll-footer)[data-v-91b6ab6c]>tr{display:inline-flex;min-inline-size:100%}:is(tbody.virtual-scroll-wrapper,thead.virtual-scroll-header,tfoot.virtual-scroll-footer)[data-v-91b6ab6c]>tr>:is(td,th){display:inline-block;align-items:center}}
+@layer components{.virtual-scrollbar-track{--vsi-scrollbar-bg:var(--vs-scrollbar-bg,var(--lightningcss-light,#e6e6e6e6)var(--lightningcss-dark,#1e1e1ee6));--vsi-scrollbar-thumb-bg:var(--vs-scrollbar-thumb-bg,var(--lightningcss-light,#0000004d)var(--lightningcss-dark,#ffffff4d));--vsi-scrollbar-thumb-hover-bg:var(--vs-scrollbar-thumb-hover-bg,var(--lightningcss-light,#0009)var(--lightningcss-dark,#fff9));--vsi-scrollbar-radius:var(--vs-scrollbar-radius,4px);--vsi-scrollbar-size:var(--vs-scrollbar-size,8px);contain:layout;background-color:var(--vsi-scrollbar-bg);border-radius:var(--vsi-scrollbar-radius);z-index:30;-webkit-user-select:none;user-select:none;pointer-events:auto;transition:opacity .2s;position:absolute}.virtual-scrollbar-track.virtual-scrollbar-track--vertical{inline-size:var(--vsi-scrollbar-size);inset-block-start:2px;inset-inline-end:2px}.virtual-scrollbar-track.virtual-scrollbar-track--horizontal{block-size:var(--vsi-scrollbar-size);inset-block-end:2px;inset-inline-start:2px}.virtual-scrollbar-thumb{background-color:var(--vsi-scrollbar-thumb-bg);border-radius:var(--vsi-scrollbar-radius);touch-action:none;pointer-events:auto;cursor:pointer;position:absolute}.virtual-scrollbar-thumb:hover,.virtual-scrollbar-thumb:active,.virtual-scrollbar-thumb.virtual-scrollbar-thumb--active{background-color:var(--vsi-scrollbar-thumb-hover-bg)}.virtual-scrollbar-thumb.virtual-scrollbar-thumb--vertical{inline-size:100%}.virtual-scrollbar-thumb.virtual-scrollbar-thumb--horizontal{block-size:100%}.virtual-scroll-container[data-v-408dd72c]{outline-offset:1px;block-size:100%;inline-size:100%;position:relative}.virtual-scroll-container[data-v-408dd72c]:not(.virtual-scroll--window){overscroll-behavior:contain;overflow:auto}.virtual-scroll-container.virtual-scroll--table[data-v-408dd72c]{display:block}.virtual-scroll-container.virtual-scroll--hide-scrollbar[data-v-408dd72c]{scrollbar-width:none;-ms-overflow-style:none}.virtual-scroll-container.virtual-scroll--hide-scrollbar[data-v-408dd72c]::-webkit-scrollbar{display:none}.virtual-scroll-container.virtual-scroll--horizontal[data-v-408dd72c],.virtual-scroll-container.virtual-scroll--both[data-v-408dd72c]{white-space:nowrap}.virtual-scroll-scrollbar-container[data-v-408dd72c]{z-index:30;pointer-events:none;block-size:0;inline-size:100%;position:sticky;inset-block-start:0;inset-inline-start:0;overflow:visible}.virtual-scroll-scrollbar-viewport[data-v-408dd72c]{pointer-events:none;position:absolute;inset-block-start:0;inset-inline-start:0}.virtual-scroll-wrapper[data-v-408dd72c]{contain:layout;position:relative}:where(.virtual-scroll--hydrated>.virtual-scroll-wrapper>.virtual-scroll-item[data-v-408dd72c]){position:absolute;inset-block-start:0;inset-inline-start:0}.virtual-scroll-item[data-v-408dd72c]{box-sizing:border-box;will-change:transform;display:grid}.virtual-scroll-item:where(.virtual-scroll--debug)[data-v-408dd72c]{background-color:#ff00000d;outline:1px dashed #ff000080}.virtual-scroll-item:where(.virtual-scroll--debug)[data-v-408dd72c]:where(:hover){z-index:100;background-color:#ff00001a}.virtual-scroll-debug-info[data-v-408dd72c]{color:#fff;pointer-events:none;z-index:100;background:#000000b3;border-radius:4px;padding:2px 4px;font-family:monospace;font-size:10px;position:absolute;inset-block-start:2px;inset-inline-end:2px}.virtual-scroll-spacer[data-v-408dd72c]{pointer-events:none}.virtual-scroll-header[data-v-408dd72c],.virtual-scroll-footer[data-v-408dd72c]{z-index:20;position:relative}.virtual-scroll--sticky[data-v-408dd72c]{position:sticky}.virtual-scroll--sticky[data-v-408dd72c]:where(.virtual-scroll-header){box-sizing:border-box;min-inline-size:100%;inset-block-start:0;inset-inline-start:0}.virtual-scroll--sticky[data-v-408dd72c]:where(.virtual-scroll-footer){box-sizing:border-box;min-inline-size:100%;inset-block-end:0;inset-inline-start:0}.virtual-scroll--sticky[data-v-408dd72c]:where(.virtual-scroll-item){z-index:10}:is(tbody.virtual-scroll-wrapper,thead.virtual-scroll-header,tfoot.virtual-scroll-footer)[data-v-408dd72c]{min-inline-size:100%;display:inline-flex}:is(tbody.virtual-scroll-wrapper,thead.virtual-scroll-header,tfoot.virtual-scroll-footer)[data-v-408dd72c]>tr{min-inline-size:100%;display:inline-flex}:is(tbody.virtual-scroll-wrapper,thead.virtual-scroll-header,tfoot.virtual-scroll-footer)[data-v-408dd72c]>tr>:is(td,th){align-items:center;display:inline-block}}
+/*$vite$:1*/

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@pdanpdan/virtual-scroll",
   "type": "module",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A high-performance virtual scroll component for Vue 3",
   "author": "",
   "license": "MIT",
   "homepage": "https://github.com/pdanpdan/virtual-scroll#readme",
   "repository": {
     "type": "git",
-    "url": "https://github.com/pdanpdan/virtual-scroll",
+    "url": "git+https://github.com/pdanpdan/virtual-scroll.git",
     "directory": "packages/virtual-scroll"
   },
   "bugs": {
@@ -38,6 +38,8 @@
   "jsdelivr": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
+    "!src/**/*.test.ts",
+    "!src/**/__tests__",
     "dist",
     "src"
   ],

package/src/components/VirtualScroll.test.ts

@@ -2328,5 +2328,41 @@ describe('virtualScroll', () => {
 
       expect(wrapper.findAll('.virtual-scroll-item').length).toBe(15);
     });
+
+    describe('table virtualization', () => {
+      it('correctly virtualizes when using table tags and constrained height', async () => {
+        const items = Array.from({ length: 1000 }, (_, i) => ({ id: i }));
+        const wrapper = mount(VirtualScroll, {
+          props: {
+            items,
+            itemSize: 40,
+            containerTag: 'table',
+            wrapperTag: 'tbody',
+            itemTag: 'tr',
+            style: { height: '400px', display: 'block' },
+          },
+          slots: {
+            item: '<td class="item">{{ index }}</td>',
+          },
+        });
+
+        await nextTick();
+        // Since it's mounted in JSDOM, we need to mock clientHeight/clientWidth if they are 0
+        const el = wrapper.element as HTMLElement;
+        Object.defineProperty(el, 'clientHeight', { value: 400, configurable: true });
+        Object.defineProperty(el, 'clientWidth', { value: 800, configurable: true });
+
+        // Trigger resize observation
+        const vs = wrapper.vm as unknown as VirtualScrollInstance<MockItem>;
+        vs.refresh();
+        await nextTick();
+        await nextTick();
+
+        // 400px height / 40px itemSize = 10 items + buffer
+        const renderedCount = wrapper.findAll('tr.virtual-scroll-item').length;
+        expect(renderedCount).toBeLessThan(30);
+        expect(renderedCount).toBeGreaterThan(10);
+      });
+    });
   });
 });

package/src/components/VirtualScroll.vue

@@ -5,6 +5,7 @@
  * Features include sticky headers/footers, RTL support, custom scrollbars, and scroll restoration.
  */
 import type {
+  ItemSlotProps,
   RenderedItem,
   ScrollAlignment,
   ScrollbarSlotProps,
@@ -66,39 +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;
-    /** Vertical gap between items. */
-    gap: number;
-    /** Horizontal gap between columns. */
-    columnGap: 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.
@@ -421,27 +390,21 @@ const extraResizeObserver = typeof window === 'undefined'
     updateHostOffset();
   });
 
-watch(headerRef, (newEl, oldEl) => {
-  if (oldEl) {
-    extraResizeObserver?.unobserve(oldEl);
-  }
-  if (newEl) {
-    extraResizeObserver?.observe(newEl);
-  } else {
-    measuredPaddingStart.value = 0;
-  }
-}, { 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);
-  } else {
-    measuredPaddingEnd.value = 0;
-  }
-}, { immediate: true });
+watchExtraRef(headerRef, measuredPaddingStart);
+watchExtraRef(footerRef, measuredPaddingEnd);
 
 onMounted(() => {
   if (hostRef.value) {
@@ -868,7 +831,7 @@ const containerStyle = computed(() => {
     ...(props.direction !== 'vertical' ? { whiteSpace: 'nowrap' as const } : {}),
   };
 
-  if (showVirtualScrollbars.value) {
+  if (showVirtualScrollbars.value || !isWindowContainer.value) {
     base.overflow = 'auto';
   }
 
@@ -883,6 +846,7 @@ const containerStyle = computed(() => {
   if (props.containerTag === 'table') {
     return {
       ...base,
+      display: 'block',
       minInlineSize: props.direction === 'vertical' ? '100%' : 'auto',
     };
   }
@@ -910,6 +874,7 @@ const verticalScrollbarProps = computed<ScrollbarSlotProps | null>(() => {
   };
 
   return {
+    axis: 'vertical',
     positionPercent: verticalScrollbar.positionPercent.value,
     viewportPercent: verticalScrollbar.viewportPercent.value,
     thumbSizePercent: verticalScrollbar.thumbSizePercent.value,
@@ -941,6 +906,7 @@ const horizontalScrollbarProps = computed<ScrollbarSlotProps | null>(() => {
   };
 
   return {
+    axis: 'horizontal',
     positionPercent: horizontalScrollbar.positionPercent.value,
     viewportPercent: horizontalScrollbar.viewportPercent.value,
     thumbSizePercent: horizontalScrollbar.thumbSizePercent.value,
@@ -998,7 +964,7 @@ const spacerStyle = computed(() => ({
  */
 function getItemStyle(item: RenderedItem<T>) {
   const style = calculateItemStyle({
-    containerTag: props.containerTag,
+    containerTag: props.containerTag || 'div',
     direction: props.direction,
     isHydrated: isHydrated.value,
     item,
@@ -1265,7 +1231,11 @@ defineExpose({
           :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>

package/src/composables/useVirtualScroll.ts

@@ -12,8 +12,13 @@ import type { MaybeRefOrGetter } from 'vue';
 /* global ScrollToOptions */
 import { computed, getCurrentInstance, nextTick, onMounted, onUnmounted, reactive, ref, toValue, watch } from 'vue';
 
+import {
+  DEFAULT_BUFFER,
+  DEFAULT_COLUMN_WIDTH,
+  DEFAULT_ITEM_SIZE,
+} from '../types';
 import { FenwickTree } from '../utils/fenwick-tree';
-import { BROWSER_MAX_SIZE, getPaddingX, getPaddingY, isElement, isScrollableElement, isScrollToIndexOptions, isWindowLike } from '../utils/scroll';
+import { BROWSER_MAX_SIZE, getPaddingX, getPaddingY, isElement, isScrollableElement, isScrollToIndexOptions, isWindowLike, scrollTo } from '../utils/scroll';
 import {
   calculateColumnRange,
   calculateItemPosition,
@@ -26,20 +31,6 @@ import {
   virtualToDisplay,
 } from '../utils/virtual-scroll-logic';
 
-export {
-  type RenderedItem,
-  type ScrollAlignment,
-  type ScrollAlignmentOptions,
-  type ScrollDetails,
-  type ScrollDirection,
-  type ScrollToIndexOptions,
-  type VirtualScrollProps,
-};
-
-export const DEFAULT_ITEM_SIZE = 40;
-export const DEFAULT_COLUMN_WIDTH = 100;
-export const DEFAULT_BUFFER = 5;
-
 /**
  * Composable for virtual scrolling logic.
  * Handles calculation of visible items, scroll events, dynamic item sizes, and programmatic scrolling.
@@ -391,8 +382,6 @@ export function useVirtualScroll<T = unknown>(propsInput: MaybeRefOrGetter<Virtu
       stickyEndY: stickyEndY.value,
       flowPaddingStartX: flowStartX.value,
       flowPaddingStartY: flowStartY.value,
-      flowPaddingEndX: flowEndX.value,
-      flowPaddingEndY: flowEndY.value,
       paddingStartX: paddingStartX.value,
       paddingStartY: paddingStartY.value,
       paddingEndX: paddingEndX.value,
@@ -425,36 +414,18 @@ export function useVirtualScroll<T = unknown>(propsInput: MaybeRefOrGetter<Virtu
     const scrollBehavior = isCorrection ? 'auto' : (behavior || 'smooth');
     isProgrammaticScroll.value = true;
 
-    if (typeof window !== 'undefined' && container === window) {
-      window.scrollTo({
-        left: (colIndex === null || colIndex === undefined) ? undefined : (isRtl.value ? finalX : Math.max(0, finalX)),
-        top: (rowIndex === null || rowIndex === undefined) ? undefined : Math.max(0, finalY),
-        behavior: scrollBehavior,
-      } as ScrollToOptions);
-    } else if (isScrollableElement(container)) {
-      const scrollOptions: ScrollToOptions = {
-        behavior: scrollBehavior,
-      };
-
-      if (colIndex !== null && colIndex !== undefined) {
-        scrollOptions.left = (isRtl.value ? finalX : Math.max(0, finalX));
-      }
-      if (rowIndex !== null && rowIndex !== undefined) {
-        scrollOptions.top = Math.max(0, finalY);
-      }
-
-      if (typeof container.scrollTo === 'function') {
-        container.scrollTo(scrollOptions);
-      } else {
-        if (scrollOptions.left !== undefined) {
-          container.scrollLeft = scrollOptions.left;
-        }
-        if (scrollOptions.top !== undefined) {
-          container.scrollTop = scrollOptions.top;
-        }
-      }
+    const scrollOptions: ScrollToOptions = {
+      behavior: scrollBehavior,
+    };
+    if (colIndex !== null && colIndex !== undefined) {
+      scrollOptions.left = isRtl.value ? finalX : Math.max(0, finalX);
+    }
+    if (rowIndex !== null && rowIndex !== undefined) {
+      scrollOptions.top = Math.max(0, finalY);
     }
 
+    scrollTo(container, scrollOptions);
+
     if (scrollBehavior === 'auto' || scrollBehavior === undefined) {
       if (colIndex !== null && colIndex !== undefined) {
         scrollX.value = (isRtl.value ? finalX : Math.max(0, finalX));
@@ -517,36 +488,18 @@ export function useVirtualScroll<T = unknown>(propsInput: MaybeRefOrGetter<Virtu
       : currentX;
     const targetY = (displayTargetY !== null) ? displayTargetY : currentY;
 
-    if (typeof window !== 'undefined' && container === window) {
-      window.scrollTo({
-        left: (x !== null && x !== undefined) ? targetX : undefined,
-        top: (y !== null && y !== undefined) ? targetY : undefined,
-        behavior: options?.behavior || 'auto',
-      } as ScrollToOptions);
-    } else if (isScrollableElement(container)) {
-      const scrollOptions: ScrollToOptions = {
-        behavior: options?.behavior || 'auto',
-      };
-
-      if (x !== null && x !== undefined) {
-        scrollOptions.left = targetX;
-      }
-      if (y !== null && y !== undefined) {
-        scrollOptions.top = targetY;
-      }
-
-      if (typeof container.scrollTo === 'function') {
-        container.scrollTo(scrollOptions);
-      } else {
-        if (scrollOptions.left !== undefined) {
-          container.scrollLeft = scrollOptions.left;
-        }
-        if (scrollOptions.top !== undefined) {
-          container.scrollTop = scrollOptions.top;
-        }
-      }
+    const scrollOptions: ScrollToOptions = {
+      behavior: options?.behavior || 'auto',
+    };
+    if (x !== null && x !== undefined) {
+      scrollOptions.left = targetX;
+    }
+    if (y !== null && y !== undefined) {
+      scrollOptions.top = targetY;
     }
 
+    scrollTo(container, scrollOptions);
+
     if (options?.behavior === 'auto' || options?.behavior === undefined) {
       if (x !== null && x !== undefined) {
         scrollX.value = targetX;
@@ -1103,7 +1056,7 @@ export function useVirtualScroll<T = unknown>(propsInput: MaybeRefOrGetter<Virtu
       const originalX = x;
       const originalY = y;
 
-      const { isStickyActive, stickyOffset } = calculateStickyItem({
+      const { isStickyActive, isStickyActiveX, isStickyActiveY, stickyOffset } = calculateStickyItem({
         index: i,
         isSticky,
         direction: direction.value,
@@ -1118,18 +1071,18 @@ export function useVirtualScroll<T = unknown>(propsInput: MaybeRefOrGetter<Virtu
         fixedWidth: fixedColumnWidth.value,
         gap: props.value.gap || 0,
         columnGap: props.value.columnGap || 0,
-        getItemQueryY: (idx) => itemSizesY.query(idx),
-        getItemQueryX: (idx) => itemSizesX.query(idx),
+        getItemQueryY: queryYCached,
+        getItemQueryX: queryXCached,
       });
 
       const offsetX = isHydrated.value
-        ? (internalScrollX.value / scaleX.value + (originalX + itemsStartVU_X - internalScrollX.value)) - wrapperStartDU_X
-        : (originalX - ssrOffsetX);
+        ? (internalScrollX.value / scaleX.value + (x + itemsStartVU_X - internalScrollX.value)) - wrapperStartDU_X
+        : (x - ssrOffsetX);
       const offsetY = isHydrated.value
-        ? (internalScrollY.value / scaleY.value + (originalY + itemsStartVU_Y - internalScrollY.value)) - wrapperStartDU_Y
-        : (originalY - ssrOffsetY);
-      const last = lastItemsMap.get(i);
+        ? (internalScrollY.value / scaleY.value + (y + itemsStartVU_Y - internalScrollY.value)) - wrapperStartDU_Y
+        : (y - ssrOffsetY);
 
+      const last = lastItemsMap.get(i);
       if (
         last
         && last.item === item
@@ -1139,6 +1092,8 @@ export function useVirtualScroll<T = unknown>(propsInput: MaybeRefOrGetter<Virtu
         && last.size.height === height
         && last.isSticky === isSticky
         && last.isStickyActive === isStickyActive
+        && last.isStickyActiveX === isStickyActiveX
+        && last.isStickyActiveY === isStickyActiveY
         && last.stickyOffset.x === stickyOffset.x
         && last.stickyOffset.y === stickyOffset.y
       ) {
@@ -1153,10 +1108,9 @@ export function useVirtualScroll<T = unknown>(propsInput: MaybeRefOrGetter<Virtu
           originalY,
           isSticky,
           isStickyActive,
-          stickyOffset: {
-            x: stickyOffset.x,
-            y: stickyOffset.y,
-          },
+          isStickyActiveX,
+          isStickyActiveY,
+          stickyOffset,
         });
       }
     }
@@ -1287,6 +1241,26 @@ export function useVirtualScroll<T = unknown>(propsInput: MaybeRefOrGetter<Virtu
     const processedRows = new Set<number>();
     const processedCols = new Set<number>();
 
+    const tryUpdateColumn = (colIdx: number, width: number) => {
+      if (colIdx >= 0 && colIdx < (props.value.columnCount || 0) && !processedCols.has(colIdx)) {
+        processedCols.add(colIdx);
+        const oldW = columnSizes.get(colIdx);
+        const targetW = width + columnGap;
+
+        if (!measuredColumns[ colIdx ] || Math.abs(oldW - targetW) > 0.1) {
+          const d = targetW - oldW;
+          if (Math.abs(d) > 0.1) {
+            columnSizes.update(colIdx, d);
+            needUpdate = true;
+            if (colIdx < firstColIndex) {
+              deltaX += d;
+            }
+          }
+          measuredColumns[ colIdx ] = 1;
+        }
+      }
+    };
+
     for (const { index, inlineSize, blockSize, element } of updates) {
       // Ignore 0-size measurements as they usually indicate hidden/detached elements
       if (inlineSize <= 0 && blockSize <= 0) {
@@ -1336,51 +1310,14 @@ export function useVirtualScroll<T = unknown>(propsInput: MaybeRefOrGetter<Virtu
       ) {
         const colIndexAttr = element.dataset.colIndex;
         if (colIndexAttr != null) {
-          const colIndex = Number.parseInt(colIndexAttr, 10);
-          if (colIndex >= 0 && colIndex < (props.value.columnCount || 0) && !processedCols.has(colIndex)) {
-            processedCols.add(colIndex);
-            const oldW = columnSizes.get(colIndex);
-            const targetW = inlineSize + columnGap;
-
-            if (!measuredColumns[ colIndex ] || Math.abs(oldW - targetW) > 0.1) {
-              const d = targetW - oldW;
-              if (Math.abs(d) > 0.1) {
-                columnSizes.update(colIndex, d);
-                needUpdate = true;
-                if (colIndex < firstColIndex) {
-                  deltaX += d;
-                }
-              }
-              measuredColumns[ colIndex ] = 1;
-            }
-          }
+          tryUpdateColumn(Number.parseInt(colIndexAttr, 10), inlineSize);
         } else {
           // If the element is a row, try to find cells with data-col-index
-          const cells = element.dataset.colIndex !== undefined
-            ? [ element ]
-            : Array.from(element.querySelectorAll('[data-col-index]')) as HTMLElement[];
+          const cells = Array.from(element.querySelectorAll('[data-col-index]')) as HTMLElement[];
 
           for (const child of cells) {
             const colIndex = Number.parseInt(child.dataset.colIndex!, 10);
-
-            if (colIndex >= 0 && colIndex < (props.value.columnCount || 0) && !processedCols.has(colIndex)) {
-              processedCols.add(colIndex);
-              const rect = child.getBoundingClientRect();
-              const w = rect.width;
-              const oldW = columnSizes.get(colIndex);
-              const targetW = w + columnGap;
-              if (!measuredColumns[ colIndex ] || Math.abs(oldW - targetW) > 0.1) {
-                const d = targetW - oldW;
-                if (Math.abs(d) > 0.1) {
-                  columnSizes.update(colIndex, d);
-                  needUpdate = true;
-                  if (colIndex < firstColIndex) {
-                    deltaX += d;
-                  }
-                }
-                measuredColumns[ colIndex ] = 1;
-              }
-            }
+            tryUpdateColumn(colIndex, child.getBoundingClientRect().width);
           }
         }
       }
@@ -1470,8 +1407,6 @@ export function useVirtualScroll<T = unknown>(propsInput: MaybeRefOrGetter<Virtu
         stickyEndY: stickyEndY.value,
         flowPaddingStartX: flowStartX.value,
         flowPaddingStartY: flowStartY.value,
-        flowPaddingEndX: flowEndX.value,
-        flowPaddingEndY: flowEndY.value,
         paddingStartX: paddingStartX.value,
         paddingStartY: paddingStartY.value,
         paddingEndX: paddingEndX.value,
@@ -1512,23 +1447,25 @@ export function useVirtualScroll<T = unknown>(propsInput: MaybeRefOrGetter<Virtu
   let directionInterval: ReturnType<typeof setInterval> | undefined;
 
   const attachEvents = (container: HTMLElement | Window | null) => {
-    if (!container || typeof window === 'undefined') {
+    if (typeof window === 'undefined') {
       return;
     }
-    const scrollTarget = container === window ? document : container;
+    const effectiveContainer = container || window;
+    const scrollTarget = (effectiveContainer === window || (isElement(effectiveContainer) && effectiveContainer === document.documentElement)) ? document : effectiveContainer;
+
     scrollTarget.addEventListener('scroll', handleScroll, { passive: true });
 
     computedStyle = null;
     updateDirection();
 
-    if (isElement(container)) {
+    if (isElement(effectiveContainer)) {
       directionObserver = new MutationObserver(() => updateDirection());
-      directionObserver.observe(container, { attributes: true, attributeFilter: [ 'dir', 'style' ] });
+      directionObserver.observe(effectiveContainer, { attributes: true, attributeFilter: [ 'dir', 'style' ] });
     }
 
     directionInterval = setInterval(updateDirection, 1000);
 
-    if (container === window) {
+    if (effectiveContainer === window) {
       viewportWidth.value = document.documentElement.clientWidth;
       viewportHeight.value = document.documentElement.clientHeight;
       scrollX.value = window.scrollX;
@@ -1541,29 +1478,28 @@ export function useVirtualScroll<T = unknown>(propsInput: MaybeRefOrGetter<Virtu
         updateHostOffset();
       };
       window.addEventListener('resize', onResize);
+
       return () => {
         scrollTarget.removeEventListener('scroll', handleScroll);
         window.removeEventListener('resize', onResize);
+        directionObserver?.disconnect();
         clearInterval(directionInterval);
         computedStyle = null;
       };
     } else {
-      viewportWidth.value = (container as HTMLElement).clientWidth;
-      viewportHeight.value = (container as HTMLElement).clientHeight;
-      scrollX.value = (container as HTMLElement).scrollLeft;
-      scrollY.value = (container as HTMLElement).scrollTop;
+      viewportWidth.value = (effectiveContainer as HTMLElement).clientWidth;
+      viewportHeight.value = (effectiveContainer as HTMLElement).clientHeight;
+      scrollX.value = (effectiveContainer as HTMLElement).scrollLeft;
+      scrollY.value = (effectiveContainer as HTMLElement).scrollTop;
 
-      resizeObserver = new ResizeObserver((entries) => {
+      resizeObserver = new ResizeObserver(() => {
         updateDirection();
-        for (const entry of entries) {
-          if (entry.target === container) {
-            viewportWidth.value = (container as HTMLElement).clientWidth;
-            viewportHeight.value = (container as HTMLElement).clientHeight;
-            updateHostOffset();
-          }
-        }
+        viewportWidth.value = (effectiveContainer as HTMLElement).clientWidth;
+        viewportHeight.value = (effectiveContainer as HTMLElement).clientHeight;
+        updateHostOffset();
       });
-      resizeObserver.observe(container as HTMLElement);
+      resizeObserver.observe(effectiveContainer as HTMLElement);
+
       return () => {
         scrollTarget.removeEventListener('scroll', handleScroll);
         resizeObserver?.disconnect();

package/src/composables/useVirtualScrollbar.test.ts

@@ -440,9 +440,7 @@ describe('useVirtualScrollbar', () => {
       await thumb.trigger('mousedown');
       expect(scrollToOffset).not.toHaveBeenCalled();
     });
-  });
 
-  describe('edge cases & cleanup', () => {
     it('handles scrollabletrackrange <= 0', async () => {
       const scrollToOffset = vi.fn();
       const { wrapper } = setup({
@@ -469,18 +467,6 @@ describe('useVirtualScrollbar', () => {
       expect(scrollToOffset).not.toHaveBeenCalled();
     });
 
-    it('handles missing track element during move', () => {
-      const { wrapper } = setup({
-        axis: 'vertical',
-        totalSize: 1000,
-        position: 0,
-        viewportSize: 200,
-        scrollToOffset: vi.fn(),
-      });
-
-      wrapper.unmount();
-    });
-
     it('handles move with missing parent track', async () => {
       const scrollToOffset = vi.fn();
       const { wrapper } = setup({
@@ -523,4 +509,18 @@ describe('useVirtualScrollbar', () => {
       expect(thumb.element.releasePointerCapture).not.toHaveBeenCalled();
     });
   });
+
+  describe('lifecycle', () => {
+    it('handles missing track element during move', () => {
+      const { wrapper } = setup({
+        axis: 'vertical',
+        totalSize: 1000,
+        position: 0,
+        viewportSize: 200,
+        scrollToOffset: vi.fn(),
+      });
+
+      wrapper.unmount();
+    });
+  });
 });

package/src/composables/useVirtualScrollbar.ts

@@ -1,3 +1,8 @@
+/**
+ * Composable for virtual scrollbar logic.
+ * Handles calculation of thumb position and size, track interactions, and dragging.
+ */
+
 import type { ScrollAxis } from '../types';
 import type { MaybeRefOrGetter } from 'vue';
 

package/src/index.ts

@@ -1,3 +1,10 @@
+/**
+ * @pdanpdan/virtual-scroll
+ *
+ * A high-performance, flexible virtual scrolling library for Vue 3.
+ * Supports massive lists and grids with coordinate scaling to bypass browser scroll limits.
+ */
+
 export { default as VirtualScroll } from './components/VirtualScroll.vue';
 export { default as VirtualScrollbar } from './components/VirtualScrollbar.vue';
 export * from './composables/useVirtualScroll';