@humanspeak/svelte-virtual-list 0.4.5 → 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,27 +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
- * @param {boolean} atBottom - Whether the list is scrolled to the bottom (unused, legacy parameter)
- * @param {boolean} wasAtBottomBeforeHeightChange - Whether the list was at bottom before a height change (unused, legacy parameter)
- * @param {SvelteVirtualListPreviousVisibleRange | null} lastVisibleRange - Previous visible range (unused, legacy parameter)
- * @param {number} [totalContentHeight] - Pre-calculated total content height; defaults to totalItems * itemHeight
- * @param {Record<number, number>} [heightCache] - Cache of measured item heights keyed by index, used in topToBottom mode to walk actual heights instead of dividing by average
- * @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,24 +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
- * @param {boolean} atBottom - Whether the list is scrolled to the bottom (unused, legacy parameter)
- * @param {boolean} wasAtBottomBeforeHeightChange - Whether the list was at bottom before a height change (unused, legacy parameter)
- * @param {SvelteVirtualListPreviousVisibleRange | null} lastVisibleRange - Previous visible range (unused, legacy parameter)
- * @param {number} [totalContentHeight] - Pre-calculated total content height; defaults to totalItems * itemHeight
- * @param {Record<number, number>} [heightCache] - Cache of measured item heights keyed by index, used in topToBottom mode to walk actual heights instead of dividing by average
- * @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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-virtual-list",
-  "version": "0.4.5",
+  "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"
   },