@humanspeak/svelte-virtual-list 0.4.4 → 0.4.6

package/dist/SvelteVirtualList.svelte

@@ -167,8 +167,7 @@
         calculateVisibleRange,
         clampValue,
         updateHeightAndScroll as utilsUpdateHeightAndScroll,
-        getScrollOffsetForIndex,
-        buildBlockSums
+        getScrollOffsetForIndex
     } from './utils/virtualList.js'
     import { createDebugInfo, shouldShowDebugInfo } from './utils/virtualListDebug.js'
     import { calculateScrollTarget } from './utils/scrollCalculation.js'
@@ -260,7 +259,7 @@
         const est = heightManager.averageHeight
         const maxScrollTop = Math.max(0, totalHeight - (height || 0))
         // Offset from start to anchored item
-        const blockSums = buildBlockSums(cache, est, items.length)
+        const blockSums = heightManager.getBlockSums()
         const offsetToIndex = getScrollOffsetForIndex(cache, est, anchorIndex, blockSums)
         const currentTop = heightManager.viewport.scrollTop
         let offsetWithin: number
@@ -286,7 +285,7 @@
         if (!pendingAnchorReconcile) return
         const cache = heightManager.getHeightCache()
         const est = heightManager.averageHeight
-        const blockSums = buildBlockSums(cache, est, items.length)
+        const blockSums = heightManager.getBlockSums()
         const offsetToIndex = getScrollOffsetForIndex(
             cache,
             est,
@@ -999,19 +998,16 @@
             }
         }
 
-        lastVisibleRange = calculateVisibleRange(
-            heightManager.scrollTop,
+        lastVisibleRange = calculateVisibleRange({
+            scrollTop: heightManager.scrollTop,
             viewportHeight,
-            heightManager.averageHeight,
-            items.length,
+            itemHeight: heightManager.averageHeight,
+            totalItems: items.length,
             bufferSize,
             mode,
-            atBottom,
-            wasAtBottomBeforeHeightChange,
-            lastVisibleRange,
-            totalHeight,
-            heightManager.getHeightCache()
-        )
+            totalContentHeight: totalHeight,
+            heightCache: heightManager.getHeightCache()
+        })
 
         return lastVisibleRange
     })

package/dist/utils/virtualList.d.ts

@@ -49,22 +49,45 @@ export declare const clampValue: (value: number, min: number, max: number) => nu
  * @returns {number} The maximum scroll position in pixels
  */
 export declare const calculateScrollPosition: (totalItems: number, itemHeight: number, containerHeight: number) => number;
+/** Options for {@link calculateVisibleRange}. */
+export interface VisibleRangeOptions {
+    scrollTop: number;
+    viewportHeight: number;
+    /** Estimated/average item height used as fallback for unmeasured items. */
+    itemHeight: number;
+    totalItems: number;
+    /** Number of extra items to render outside the visible area. */
+    bufferSize: number;
+    mode: SvelteVirtualListMode;
+    /** Pre-calculated total content height; defaults to `totalItems * itemHeight`. */
+    totalContentHeight?: number;
+    /** Measured item heights keyed by index; used in topToBottom mode to walk actual heights instead of dividing by average. */
+    heightCache?: Record<number, number>;
+}
 /**
  * Determines the range of items that should be rendered in the virtual list.
  *
- * This function calculates which items should be visible based on the current scroll position,
- * viewport size, and scroll direction. It includes a buffer zone to enable smooth scrolling
+ * Calculates which items should be visible based on the current scroll position,
+ * viewport size, and scroll direction. Includes a buffer zone to enable smooth scrolling
  * and prevent visible gaps during rapid scroll movements.
  *
- * @param {number} scrollTop - Current scroll position in pixels
- * @param {number} viewportHeight - Height of the visible area in pixels
- * @param {number} itemHeight - Height of each list item in pixels
- * @param {number} totalItems - Total number of items in the list
- * @param {number} bufferSize - Number of items to render outside the visible area
- * @param {SvelteVirtualListMode} mode - Scroll direction mode
- * @returns {SvelteVirtualListPreviousVisibleRange} Range of indices to render
+ * @param options - Inputs used to compute the visible range (see {@link VisibleRangeOptions}).
+ * @returns Range of indices to render.
+ *
+ * @example
+ * ```ts
+ * const range = calculateVisibleRange({
+ *     scrollTop: 200,
+ *     viewportHeight: 400,
+ *     itemHeight: 40,
+ *     totalItems: 1000,
+ *     bufferSize: 2,
+ *     mode: 'topToBottom'
+ * })
+ * // range => { start: 3, end: 15 }
+ * ```
  */
-export declare const calculateVisibleRange: (scrollTop: number, viewportHeight: number, itemHeight: number, totalItems: number, bufferSize: number, mode: SvelteVirtualListMode, atBottom: boolean, wasAtBottomBeforeHeightChange: boolean, lastVisibleRange: SvelteVirtualListPreviousVisibleRange | null, totalContentHeight?: number, heightCache?: Record<number, number>) => SvelteVirtualListPreviousVisibleRange;
+export declare const calculateVisibleRange: ({ scrollTop, viewportHeight, itemHeight, totalItems, bufferSize, mode, totalContentHeight, heightCache }: VisibleRangeOptions) => SvelteVirtualListPreviousVisibleRange;
 /**
  * Calculates the CSS transform value for positioning the virtual list items.
  *

package/dist/utils/virtualList.js

@@ -56,19 +56,27 @@ export const calculateScrollPosition = (totalItems, itemHeight, containerHeight)
 /**
  * Determines the range of items that should be rendered in the virtual list.
  *
- * This function calculates which items should be visible based on the current scroll position,
- * viewport size, and scroll direction. It includes a buffer zone to enable smooth scrolling
+ * Calculates which items should be visible based on the current scroll position,
+ * viewport size, and scroll direction. Includes a buffer zone to enable smooth scrolling
  * and prevent visible gaps during rapid scroll movements.
  *
- * @param {number} scrollTop - Current scroll position in pixels
- * @param {number} viewportHeight - Height of the visible area in pixels
- * @param {number} itemHeight - Height of each list item in pixels
- * @param {number} totalItems - Total number of items in the list
- * @param {number} bufferSize - Number of items to render outside the visible area
- * @param {SvelteVirtualListMode} mode - Scroll direction mode
- * @returns {SvelteVirtualListPreviousVisibleRange} Range of indices to render
+ * @param options - Inputs used to compute the visible range (see {@link VisibleRangeOptions}).
+ * @returns Range of indices to render.
+ *
+ * @example
+ * ```ts
+ * const range = calculateVisibleRange({
+ *     scrollTop: 200,
+ *     viewportHeight: 400,
+ *     itemHeight: 40,
+ *     totalItems: 1000,
+ *     bufferSize: 2,
+ *     mode: 'topToBottom'
+ * })
+ * // range => { start: 3, end: 15 }
+ * ```
  */
-export const calculateVisibleRange = (scrollTop, viewportHeight, itemHeight, totalItems, bufferSize, mode, atBottom, wasAtBottomBeforeHeightChange, lastVisibleRange, totalContentHeight, heightCache) => {
+export const calculateVisibleRange = ({ scrollTop, viewportHeight, itemHeight, totalItems, bufferSize, mode, totalContentHeight, heightCache }) => {
     if (mode === 'bottomToTop') {
         const visibleCount = Math.ceil(viewportHeight / itemHeight) + 1;
         // In bottomToTop mode, scrollTop represents distance from the total content end
@@ -92,8 +100,25 @@ export const calculateVisibleRange = (scrollTop, viewportHeight, itemHeight, tot
         return { start, end };
     }
     else {
-        const start = Math.floor(scrollTop / itemHeight);
-        const end = Math.min(totalItems, start + Math.ceil(viewportHeight / itemHeight) + 1);
+        // Walk forward through measured heights to find the correct start index
+        // instead of dividing by average height (which is wrong for variable-height items).
+        let start = 0;
+        let acc = 0;
+        while (start < totalItems) {
+            const h = getValidHeight(heightCache?.[start], itemHeight);
+            if (acc + h > scrollTop)
+                break;
+            acc += h;
+            start++;
+        }
+        // Walk forward from start to find end
+        let end = start;
+        let viewAcc = 0;
+        while (end < totalItems && viewAcc < viewportHeight) {
+            viewAcc += getValidHeight(heightCache?.[end], itemHeight);
+            end++;
+        }
+        end = Math.min(totalItems, end + 1); // +1 to ensure partial items are visible
         // Safeguard for topToBottom: ensure last item is fully visible when at max scroll
         const totalHeight = totalContentHeight ?? totalItems * itemHeight;
         const maxScrollTop = Math.max(0, totalHeight - viewportHeight);
@@ -104,11 +129,9 @@ export const calculateVisibleRange = (scrollTop, viewportHeight, itemHeight, tot
             // Pack from the end using measured heights when available: walk backward until viewport filled
             const adjustedEnd = totalItems;
             let startCore = adjustedEnd;
-            let acc = 0;
-            const getH = (i) => getValidHeight(heightCache ? heightCache[i] : undefined, itemHeight);
-            while (startCore > 0 && acc < viewportHeight) {
-                const h = getH(startCore - 1);
-                acc += h;
+            let backAcc = 0;
+            while (startCore > 0 && backAcc < viewportHeight) {
+                backAcc += getValidHeight(heightCache?.[startCore - 1], itemHeight);
                 startCore -= 1;
             }
             return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-virtual-list",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "A lightweight, high-performance virtual list component for Svelte 5 that renders large datasets with minimal memory usage. Features include dynamic height support, smooth scrolling, TypeScript support, and efficient DOM recycling. Ideal for infinite scrolling lists, data tables, chat interfaces, and any application requiring the rendering of thousands of items without compromising performance. Zero dependencies and fully customizable.",
   "keywords": [
     "svelte",
@@ -73,8 +73,8 @@
     "@testing-library/svelte": "^5.3.1",
     "@testing-library/user-event": "^14.6.1",
     "@types/node": "^25.5.0",
-    "@typescript-eslint/eslint-plugin": "^8.57.2",
-    "@typescript-eslint/parser": "^8.57.2",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
     "@vitest/coverage-v8": "^4.1.2",
     "eslint": "^10.1.0",
     "eslint-config-prettier": "^10.1.8",
@@ -90,12 +90,12 @@
     "prettier-plugin-svelte": "^3.5.1",
     "prettier-plugin-tailwindcss": "^0.7.2",
     "publint": "^0.3.18",
-    "svelte": "^5.55.0",
+    "svelte": "^5.55.1",
     "svelte-check": "^4.4.5",
     "tailwindcss": "^4.2.2",
     "tw-animate-css": "^1.4.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.57.2",
+    "typescript-eslint": "^8.58.0",
     "vite": "^8.0.3",
     "vitest": "^4.1.2"
   },