@humanspeak/svelte-virtual-list 0.4.5 → 0.5.0

package/dist/utils/virtualList.js

@@ -56,165 +56,111 @@ 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
+ * and viewport size. 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
+ * })
+ * // range => { start: 3, end: 15 }
+ * ```
  */
-export const calculateVisibleRange = (scrollTop, viewportHeight, itemHeight, totalItems, bufferSize, mode, atBottom, wasAtBottomBeforeHeightChange, lastVisibleRange, totalContentHeight, heightCache) => {
-    if (mode === 'bottomToTop') {
-        const visibleCount = Math.ceil(viewportHeight / itemHeight) + 1;
-        // In bottomToTop mode, scrollTop represents distance from the total content end
-        // scrollTop = 0 means we're at the beginning (showing first items)
-        // scrollTop = maxScrollTop means we're at the end (showing last items)
-        const totalHeight = totalContentHeight ?? totalItems * itemHeight;
-        const maxScrollTop = Math.max(0, totalHeight - viewportHeight);
-        // Convert scrollTop to "distance from start" for bottomToTop
-        const distanceFromStart = maxScrollTop - scrollTop;
-        const startIndex = Math.floor(distanceFromStart / itemHeight);
-        // Safeguard: handle edge cases
-        if (startIndex < 0) {
-            // We're scrolled beyond the maximum (showing first items)
-            const start = 0;
-            const end = Math.min(totalItems, visibleCount + bufferSize * 2);
-            return { start, end };
-        }
-        // Add buffer to both ends
-        const start = Math.max(0, startIndex - bufferSize);
-        const end = Math.min(totalItems, startIndex + visibleCount + bufferSize);
-        return { start, end };
+export const calculateVisibleRange = ({ scrollTop, viewportHeight, itemHeight, totalItems, bufferSize, totalContentHeight, heightCache }) => {
+    // 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++;
     }
-    else {
-        // 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);
-        // Use strict tolerance to avoid premature bottom anchoring that leaves a visible gap
-        const tolerance = Math.max(1, Math.floor(itemHeight * BOTTOM_TOLERANCE_FACTOR));
-        const isAtBottom = Math.abs(scrollTop - maxScrollTop) <= tolerance;
-        if (isAtBottom) {
-            // Pack from the end using measured heights when available: walk backward until viewport filled
-            const adjustedEnd = totalItems;
-            let startCore = adjustedEnd;
-            let backAcc = 0;
-            while (startCore > 0 && backAcc < viewportHeight) {
-                backAcc += getValidHeight(heightCache?.[startCore - 1], itemHeight);
-                startCore -= 1;
-            }
-            return {
-                start: Math.max(0, startCore - bufferSize),
-                end: adjustedEnd
-            };
+    // 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: ensure last item is fully visible when at max scroll
+    const totalHeight = totalContentHeight ?? totalItems * itemHeight;
+    const maxScrollTop = Math.max(0, totalHeight - viewportHeight);
+    // Use strict tolerance to avoid prematurely treating the list as scrolled to the end.
+    const tolerance = Math.max(1, Math.floor(itemHeight * BOTTOM_TOLERANCE_FACTOR));
+    const isAtBottom = Math.abs(scrollTop - maxScrollTop) <= tolerance;
+    if (isAtBottom) {
+        // Pack from the end using measured heights when available: walk backward until viewport filled
+        const adjustedEnd = totalItems;
+        let startCore = adjustedEnd;
+        let backAcc = 0;
+        while (startCore > 0 && backAcc < viewportHeight) {
+            backAcc += getValidHeight(heightCache?.[startCore - 1], itemHeight);
+            startCore -= 1;
         }
-        // Add buffer to both ends
-        const finalStart = Math.max(0, start - bufferSize);
-        const finalEnd = Math.min(totalItems, end + bufferSize);
         return {
-            start: finalStart,
-            end: finalEnd
+            start: Math.max(0, startCore - bufferSize),
+            end: adjustedEnd
         };
     }
+    // Add buffer to both ends
+    const finalStart = Math.max(0, start - bufferSize);
+    const finalEnd = Math.min(totalItems, end + bufferSize);
+    return {
+        start: finalStart,
+        end: finalEnd
+    };
 };
 /**
  * Calculates the CSS transform value for positioning the virtual list items.
  *
  * This function determines the vertical offset needed to position the visible items
- * correctly within the viewport, accounting for the scroll direction and current
- * visible range.
+ * correctly within the viewport.
  *
- * @param {SvelteVirtualListMode} mode - Scroll direction mode
  * @param {number} totalItems - Total number of items in the list
- * @param {number} visibleEnd - Index of the last visible item
  * @param {number} visibleStart - Index of the first visible item
  * @param {number} itemHeight - Height of each list item in pixels
- * @param {number} viewportHeight - Height of the viewport in pixels
+ * @param {Record<number, number>} [heightCache] - Cache of measured item heights
  * @returns {number} The calculated transform Y value in pixels
  */
-export const calculateTransformY = (mode, totalItems, visibleEnd, visibleStart, itemHeight, viewportHeight, totalContentHeight, heightCache, measuredFallbackHeight) => {
-    const effectiveViewport = viewportHeight || measuredFallbackHeight || 0;
-    if (mode === 'bottomToTop') {
-        // In bottomToTop mode, position items so they stack from bottom up
-        const actualTotalHeight = totalContentHeight ?? totalItems * itemHeight;
-        // Calculate transform to position visible items correctly.
-        // Use measured heights when available to avoid oscillation caused by
-        // averageHeight changes shifting (totalItems - visibleEnd) * avg.
-        let basicTransform;
-        if (heightCache) {
-            const offsetToVisibleEnd = getScrollOffsetForIndex(heightCache, itemHeight, visibleEnd);
-            basicTransform = actualTotalHeight - offsetToVisibleEnd;
-        }
-        else {
-            basicTransform = (totalItems - visibleEnd) * itemHeight;
-        }
-        // When content is smaller than viewport, push to bottom
-        const bottomOffset = Math.max(0, effectiveViewport - actualTotalHeight);
-        // Snap to integer pixels to avoid subpixel oscillation
-        return Math.round(basicTransform + bottomOffset);
-    }
-    else {
-        // For topToBottom, prefer precise offset using measured heights when available
-        if (heightCache) {
-            const offset = getScrollOffsetForIndex(heightCache, itemHeight, visibleStart);
-            return Math.max(0, Math.round(offset));
-        }
-        return Math.round(visibleStart * itemHeight);
+export const calculateTransformY = (totalItems, visibleStart, itemHeight, heightCache) => {
+    // Prefer precise offset using measured heights when available
+    if (heightCache) {
+        const offset = getScrollOffsetForIndex(heightCache, itemHeight, visibleStart);
+        return Math.max(0, Math.round(offset));
     }
+    return Math.round(visibleStart * itemHeight);
 };
 /**
  * Updates the virtual list's height and scroll position when necessary.
  *
  * This function handles dynamic updates to the virtual list's dimensions and scroll
- * position, particularly important when the container size changes or when switching
- * scroll directions. When immediate is true, it forces an immediate update of the
- * height and scroll position.
+ * position, particularly important when the container size changes. When immediate
+ * is true, it forces an immediate update of the height and scroll position.
  *
  * @param {VirtualListState} state - Current state of the virtual list
  * @param {VirtualListSetters} setters - State setters for updating list properties
  * @param {boolean} immediate - Whether to perform the update immediately
  */
 export const updateHeightAndScroll = (state, setters, immediate = false) => {
-    const { initialized, mode, containerElement, viewportElement, calculatedItemHeight, scrollTop } = state;
-    const { setHeight, setScrollTop } = setters;
+    const { initialized, containerElement, viewportElement } = state;
+    const { setHeight } = setters;
     if (immediate) {
         if (containerElement && viewportElement && initialized) {
             const newHeight = containerElement.getBoundingClientRect().height;
             setHeight(newHeight);
-            if (mode === 'bottomToTop') {
-                const visibleIndex = Math.floor(scrollTop / calculatedItemHeight);
-                const newScrollTop = visibleIndex * calculatedItemHeight;
-                viewportElement.scrollTop = newScrollTop;
-                setScrollTop(newScrollTop);
-            }
         }
     }
 };
@@ -245,7 +191,7 @@ export const updateHeightAndScroll = (state, setters, immediate = false) => {
  *   40
  * )
  */
-export const calculateAverageHeight = (itemElements, visibleRange, heightCache, currentItemHeight, dirtyItems, currentTotalHeight = 0, currentValidCount = 0, mode = 'topToBottom') => {
+export const calculateAverageHeight = (itemElements, visibleRange, heightCache, currentItemHeight, dirtyItems, currentTotalHeight = 0, currentValidCount = 0) => {
     const validElements = itemElements.filter((el) => el);
     if (validElements.length === 0) {
         return {
@@ -269,16 +215,7 @@ export const calculateAverageHeight = (itemElements, visibleRange, heightCache,
         // Process only dirty items
         dirtyItems.forEach((itemIndex) => {
             // Map original item index to position in itemElements array
-            let elementIndex;
-            if (mode === 'bottomToTop') {
-                // In bottomToTop, itemElements is reversed relative to the visible range
-                // elementIndex should be based on position within the actual array, not theoretical end
-                elementIndex = validElements.length - 1 - (itemIndex - visibleRange.start);
-            }
-            else {
-                // In topToBottom, itemElements is normal: [item0, item1, ..., item44, item45]
-                elementIndex = itemIndex - visibleRange.start;
-            }
+            const elementIndex = itemIndex - visibleRange.start;
             const element = validElements[elementIndex];
             if (element && elementIndex >= 0 && elementIndex < validElements.length) {
                 try {
@@ -326,9 +263,7 @@ export const calculateAverageHeight = (itemElements, visibleRange, heightCache,
     else {
         // Original behavior: process all visible items
         validElements.forEach((el, i) => {
-            const itemIndex = mode === 'bottomToTop'
-                ? Math.max(0, (visibleRange.end ?? visibleRange.start + validElements.length) - 1 - i)
-                : visibleRange.start + i;
+            const itemIndex = visibleRange.start + i;
             if (!newHeightCache[itemIndex]) {
                 try {
                     const height = el.getBoundingClientRect().height;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@humanspeak/svelte-virtual-list",
-  "version": "0.4.5",
-  "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.",
+  "version": "0.5.0",
+  "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, activity feeds, and any application requiring the rendering of thousands of items without compromising performance. Zero dependencies and fully customizable.",
   "keywords": [
     "svelte",
     "virtual-list",
@@ -59,51 +59,51 @@
     "esm-env": "^1.2.2"
   },
   "devDependencies": {
-    "@eslint/compat": "^2.0.3",
+    "@eslint/compat": "^2.1.0",
     "@eslint/js": "^10.0.1",
     "@faker-js/faker": "^10.4.0",
-    "@playwright/cli": "^0.1.1",
-    "@playwright/test": "^1.58.2",
+    "@playwright/cli": "^0.1.13",
+    "@playwright/test": "^1.60.0",
     "@sveltejs/adapter-auto": "^7.0.1",
-    "@sveltejs/kit": "^2.55.0",
+    "@sveltejs/kit": "^2.61.1",
     "@sveltejs/package": "^2.5.7",
-    "@sveltejs/vite-plugin-svelte": "^7.0.0",
-    "@tailwindcss/vite": "^4.2.2",
+    "@sveltejs/vite-plugin-svelte": "^7.1.2",
+    "@tailwindcss/vite": "^4.3.0",
     "@testing-library/jest-dom": "^6.9.1",
     "@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",
-    "@vitest/coverage-v8": "^4.1.2",
-    "eslint": "^10.1.0",
+    "@types/node": "^25.9.1",
+    "@typescript-eslint/eslint-plugin": "^8.60.0",
+    "@typescript-eslint/parser": "^8.60.0",
+    "@vitest/coverage-v8": "^4.1.7",
+    "eslint": "^10.4.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-svelte": "^3.16.0",
+    "eslint-plugin-svelte": "^3.17.1",
     "eslint-plugin-unused-imports": "^4.4.1",
-    "globals": "^17.4.0",
+    "globals": "^17.6.0",
     "husky": "^9.1.7",
-    "jsdom": "^29.0.1",
-    "mprocs": "^0.9.2",
-    "prettier": "^3.8.1",
+    "jsdom": "^29.1.1",
+    "mprocs": "^0.9.3",
+    "prettier": "^3.8.3",
     "prettier-plugin-organize-imports": "^4.3.0",
-    "prettier-plugin-svelte": "^3.5.1",
-    "prettier-plugin-tailwindcss": "^0.7.2",
-    "publint": "^0.3.18",
-    "svelte": "^5.55.0",
-    "svelte-check": "^4.4.5",
-    "tailwindcss": "^4.2.2",
+    "prettier-plugin-svelte": "^4.0.1",
+    "prettier-plugin-tailwindcss": "^0.8.0",
+    "publint": "^0.3.21",
+    "svelte": "^5.55.9",
+    "svelte-check": "^4.4.8",
+    "tailwindcss": "^4.3.0",
     "tw-animate-css": "^1.4.0",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.57.2",
-    "vite": "^8.0.3",
-    "vitest": "^4.1.2"
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.60.0",
+    "vite": "^8.0.14",
+    "vitest": "^4.1.7"
   },
   "peerDependencies": {
     "svelte": "^5.0.0"
   },
   "volta": {
-    "node": "24.13.0"
+    "node": "24.15.0"
   },
   "publishConfig": {
     "access": "public"