@humanspeak/svelte-virtual-list 0.3.8 → 0.3.9

package/dist/SvelteVirtualList.svelte

@@ -163,9 +163,9 @@
     import { createRafScheduler } from './utils/raf.js'
     import { isSignificantHeightChange } from './utils/heightChangeDetection.js'
     import {
-        calculateScrollPosition,
         calculateTransformY,
         calculateVisibleRange,
+        clampValue,
         updateHeightAndScroll as utilsUpdateHeightAndScroll,
         getScrollOffsetForIndex,
         buildBlockSums
@@ -290,23 +290,16 @@
             Math.max(0, lastAnchorIndex),
             blockSums
         )
-        const maxScrollTop = Math.max(0, totalHeight() - (height || 0))
+        const maxScrollTop = clampValue(totalHeight() - (height || 0), 0, Infinity)
         let targetTop: number
         if (mode === 'bottomToTop') {
-            const distanceFromStart = Math.max(0, offsetToIndex + lastAnchorOffset)
-            targetTop = Math.max(
-                0,
-                Math.min(maxScrollTop, Math.round(maxScrollTop - distanceFromStart))
-            )
+            const distanceFromStart = clampValue(offsetToIndex + lastAnchorOffset, 0, Infinity)
+            targetTop = clampValue(Math.round(maxScrollTop - distanceFromStart), 0, maxScrollTop)
         } else {
-            targetTop = Math.max(
-                0,
-                Math.min(maxScrollTop, Math.round(offsetToIndex + lastAnchorOffset))
-            )
+            targetTop = clampValue(Math.round(offsetToIndex + lastAnchorOffset), 0, maxScrollTop)
         }
         if (Math.abs(heightManager.viewport.scrollTop - targetTop) >= 2) {
-            heightManager.viewport.scrollTop = targetTop
-            heightManager.scrollTop = targetTop
+            syncScrollTop(targetTop)
         }
         pendingAnchorReconcile = false
     }
@@ -387,6 +380,23 @@
         }
     }
 
+    /**
+     * Synchronizes the scroll position between the viewport element and internal state.
+     *
+     * This helper consolidates the repeated pattern of updating both
+     * heightManager.viewport.scrollTop and heightManager.scrollTop together,
+     * ensuring they stay in sync.
+     *
+     * @param {number} value - The scroll position to set
+     * @param {boolean} round - Whether to round the value to the nearest integer (default: false)
+     */
+    const syncScrollTop = (value: number, round = false) => {
+        if (!heightManager.viewportElement) return
+        const scrollValue = round ? Math.round(value) : value
+        heightManager.viewport.scrollTop = scrollValue
+        heightManager.scrollTop = scrollValue
+    }
+
     // Dynamic update coordination to avoid UA scroll anchoring interference
     let suppressBottomAnchoringUntilMs = $state(0)
 
@@ -508,8 +518,7 @@
             // Step 1: Scroll to approximate position to ensure Item 0 gets rendered in virtual viewport
             const approximateScrollTop = Math.max(0, totalHeight() - height)
             log('[SVL] b2t-correction-approx', { approximateScrollTop })
-            heightManager.viewport.scrollTop = approximateScrollTop
-            heightManager.scrollTop = approximateScrollTop
+            syncScrollTop(approximateScrollTop)
 
             // Step 2: Use native scrollIntoView for precise bottom-edge positioning after DOM updates
             tick().then(() => {
@@ -572,13 +581,12 @@
             }
         }
         if (Math.abs(heightChangeAboveViewport) > 2) {
-            const newScrollTop = Math.min(
-                maxScrollTop,
-                Math.max(0, currentScrollTop + heightChangeAboveViewport)
+            const newScrollTop = clampValue(
+                currentScrollTop + heightChangeAboveViewport,
+                0,
+                maxScrollTop
             )
-
-            heightManager.viewport.scrollTop = newScrollTop
-            heightManager.scrollTop = newScrollTop
+            syncScrollTop(newScrollTop)
         }
     }
 
@@ -613,6 +621,8 @@
     // Infinite scroll: trigger onLoadMore when approaching end of list
     $effect(() => {
         if (!BROWSER || !onLoadMore || !hasMore || isLoadingMore) return
+        // Skip loading during bottomToTop initialization (init path renders all items artificially)
+        if (mode === 'bottomToTop' && !bottomToTopScrollComplete) return
 
         const range = visibleItems()
         const atLoadingEdge = range.end >= items.length - loadMoreThreshold
@@ -667,11 +677,12 @@
                         const isAtBottom = Math.abs(currentScrollTop - maxScrollTop) <= tolerance
                         if (isAtBottom) {
                             // Adjust scrollTop by total height delta to hold bottom anchor
-                            const adjusted = Math.round(
-                                Math.min(maxScrollTop, Math.max(0, currentScrollTop + deltaTotal))
+                            const adjusted = clampValue(
+                                currentScrollTop + deltaTotal,
+                                0,
+                                maxScrollTop
                             )
-                            heightManager.viewport.scrollTop = adjusted
-                            heightManager.scrollTop = adjusted
+                            syncScrollTop(adjusted, true)
                         }
                     }
                 }
@@ -703,6 +714,9 @@
     let lastItemsLength = $state(0)
     // Track last observed total height to compute precise deltas on item count changes
     let lastTotalHeightObserved = $state(0)
+    // For bottomToTop mode: keep init path active until scroll positioning is complete
+    // This ensures Item 0 stays in the DOM throughout initialization
+    let bottomToTopScrollComplete = $state(false)
 
     /**
      * CRITICAL: O(1) Reactive Total Height Calculation
@@ -794,9 +808,7 @@
 
             if (shouldCorrect) {
                 // Round to avoid subpixel positioning issues in bottomToTop mode
-                const roundedTargetScrollTop = Math.round(targetScrollTop)
-                heightManager.viewport.scrollTop = roundedTargetScrollTop
-                heightManager.scrollTop = roundedTargetScrollTop
+                syncScrollTop(targetScrollTop, true)
             }
 
             // Track if user has scrolled significantly away from bottom
@@ -852,10 +864,12 @@
                 // If near the bottom, this naturally pins to the new max; otherwise it preserves the current content.
                 programmaticScrollInProgress = true
                 void heightManager.runDynamicUpdate(() => {
-                    const unclamped = currentScrollTop + deltaMax
-                    const newScrollTop = Math.max(0, Math.min(nextMaxScrollTop, unclamped))
-                    heightManager.viewport.scrollTop = newScrollTop
-                    heightManager.scrollTop = newScrollTop
+                    const newScrollTop = clampValue(
+                        currentScrollTop + deltaMax,
+                        0,
+                        nextMaxScrollTop
+                    )
+                    syncScrollTop(newScrollTop)
                     log('[SVL] items-length-change:applied', {
                         instanceId,
                         previousScrollTop: currentScrollTop,
@@ -871,23 +885,20 @@
                     // Reconcile on next frame in case measured heights adjust totals
                     requestAnimationFrame(() => {
                         const beforeReconcileScrollTop = heightManager.viewport.scrollTop
-                        const reconciledNextMax = Math.max(0, totalHeight() - height)
+                        const reconciledNextMax = clampValue(totalHeight() - height, 0, Infinity)
                         const reconciledDeltaMaxChange = reconciledNextMax - nextMaxScrollTop
                         // Desired position is to maintain distance-from-end; equivalently keep (max - scrollTop) constant.
-                        const desiredScrollTop = Math.max(
+                        const desiredScrollTop = clampValue(
+                            newScrollTop + reconciledDeltaMaxChange,
                             0,
-                            Math.min(reconciledNextMax, newScrollTop + reconciledDeltaMaxChange)
+                            reconciledNextMax
                         )
                         // Snap to integer pixels to prevent oscillation due to subpixel rounding
                         const desiredRounded = Math.round(desiredScrollTop)
                         const diffToDesired = desiredRounded - heightManager.viewport.scrollTop
                         if (Math.abs(diffToDesired) >= 2) {
-                            const adjusted = Math.max(
-                                0,
-                                Math.min(reconciledNextMax, desiredRounded)
-                            )
-                            heightManager.viewport.scrollTop = adjusted
-                            heightManager.scrollTop = adjusted
+                            const adjusted = clampValue(desiredRounded, 0, reconciledNextMax)
+                            syncScrollTop(adjusted)
                             log('[SVL] items-length-change:reconciled', {
                                 instanceId,
                                 beforeReconcileScrollTop,
@@ -963,31 +974,18 @@
         if (!items.length) return { start: 0, end: 0 } as SvelteVirtualListPreviousVisibleRange
         const viewportHeight = height || 0
 
-        // For bottomToTop mode, don't calculate visible range until properly initialized
-        // This prevents showing wrong items when scrollTop starts at 0
-        if (
-            mode === 'bottomToTop' &&
-            !heightManager.initialized &&
-            heightManager.scrollTop === 0 &&
-            viewportHeight > 0
-        ) {
-            // Calculate what the correct scroll position should be
-            const targetScrollTop = Math.max(0, totalHeight() - viewportHeight)
-
-            // Use the target scroll position for visible range calculation
-            lastVisibleRange = calculateVisibleRange(
-                targetScrollTop,
-                viewportHeight,
-                heightManager.averageHeight,
-                items.length,
-                bufferSize,
-                mode,
-                atBottom,
-                wasAtBottomBeforeHeightChange,
-                lastVisibleRange,
-                totalHeight(),
-                heightManager.getHeightCache()
-            )
+        // For bottomToTop mode, always render items starting from index 0 during initialization
+        // This ensures Item 0 is in the DOM so we can use scrollIntoView for precise positioning
+        // The scrollIntoView in updateHeightAndScroll will handle correct alignment after heights are measured
+        // Use bottomToTopScrollComplete (not just initialized) to keep init path active until scroll is done
+        if (mode === 'bottomToTop' && !bottomToTopScrollComplete) {
+            // Use a reasonable default if viewport height isn't measured yet
+            const effectiveViewport = viewportHeight || 400
+            const visibleCount = Math.ceil(effectiveViewport / heightManager.averageHeight) + 1
+            lastVisibleRange = {
+                start: 0,
+                end: Math.min(items.length, visibleCount + bufferSize * 2)
+            } as SvelteVirtualListPreviousVisibleRange
 
             return lastVisibleRange
         }
@@ -1099,7 +1097,8 @@
             mode
         })
         if (!heightManager.initialized && mode === 'bottomToTop') {
-            // Deterministic init order: double RAF + microtask, then apply bottom anchoring
+            // bottomToTop initialization: use scrollIntoView on Item 0 for precise positioning
+            // visibleItems() guarantees Item 0 is rendered during initialization
             tick().then(() => {
                 requestAnimationFrame(() => {
                     requestAnimationFrame(() => {
@@ -1107,11 +1106,7 @@
                         const measuredHeight =
                             heightManager.container.getBoundingClientRect().height
                         height = measuredHeight
-                        const targetScrollTop = calculateScrollPosition(
-                            items.length,
-                            heightManager.averageHeight,
-                            measuredHeight
-                        )
+
                         // Instance jitter to avoid same-frame collisions when two lists init together
                         const cleanedId = String(instanceId)
                             .toLowerCase()
@@ -1121,32 +1116,48 @@
                         const jitterMs = Number.isNaN(parsed)
                             ? Math.floor(Math.random() * 3)
                             : parsed % 3
-                        log('b2t-init', { measuredHeight, targetScrollTop, jitterMs })
+
                         setTimeout(() => {
-                            heightManager.viewport.scrollTop = targetScrollTop
-                            heightManager.scrollTop = targetScrollTop
+                            // Step 1: Set initialized (for other purposes like scroll event handling)
+                            // The init path in visibleItems() stays active until bottomToTopScrollComplete
+                            if (!heightManager.initialized) {
+                                heightManager.initialized = true
+                            }
+
+                            // Step 2: Use scrollIntoView on Item 0 for precise positioning
+                            // Use double RAF to ensure heights are measured and layout is stable
                             requestAnimationFrame(() => {
-                                // Guard: only transition false -> true to avoid invariant error
-                                if (!heightManager.initialized) heightManager.initialized = true
-                                // Post-init verification: ensure item 0 bottom aligns; fallback to native
-                                tick().then(() => {
+                                requestAnimationFrame(() => {
+                                    // Item 0 is guaranteed to be in DOM due to init path
+                                    // Skip if user has already scrolled (scrollTop significantly != 0)
+                                    const currentScroll = heightManager.viewport.scrollTop
+                                    const userHasScrolled =
+                                        currentScroll > heightManager.averageHeight
                                     const el = heightManager.viewport.querySelector(
                                         '[data-original-index="0"]'
                                     ) as HTMLElement | null
-                                    if (!el) return
-                                    const cont = heightManager.viewport.getBoundingClientRect()
-                                    const r = el.getBoundingClientRect()
-                                    const tol = 4
-                                    const aligned =
-                                        Math.abs(cont.y + cont.height - (r.y + r.height)) <= tol
-                                    if (!aligned) {
-                                        el.scrollIntoView({ block: 'end', inline: 'nearest' })
-                                        heightManager.scrollTop = heightManager.viewport.scrollTop
-                                        log('b2t-init-native-fallback', {
-                                            containerBottom: cont.y + cont.height,
-                                            itemBottom: r.y + r.height
+
+                                    if (el && !userHasScrolled) {
+                                        el.scrollIntoView({
+                                            block: 'end',
+                                            inline: 'nearest'
                                         })
+                                        heightManager.scrollTop = heightManager.viewport.scrollTop
+                                    } else if (userHasScrolled) {
+                                        // Sync internal state with current scroll
+                                        heightManager.scrollTop = currentScroll
                                     }
+
+                                    // Step 3: Mark scroll complete - switches visibleItems to normal mode
+                                    requestAnimationFrame(() => {
+                                        bottomToTopScrollComplete = true
+                                        // Reset bottom-anchoring flag to prevent stale state from init
+                                        // affecting later operations (e.g., adding items while scrolled away)
+                                        wasAtBottomBeforeHeightChange = false
+                                        // Suppress bottom-anchoring briefly to let heights stabilize
+                                        // after switching to normal mode
+                                        suppressBottomAnchoringUntilMs = performance.now() + 200
+                                    })
                                 })
                             })
                         }, jitterMs)
@@ -1371,7 +1382,7 @@
                     `scroll: index ${targetIndex} is out of bounds (0-${items.length - 1})`
                 )
             } else {
-                targetIndex = Math.max(0, Math.min(targetIndex, items.length - 1))
+                targetIndex = clampValue(targetIndex, 0, items.length - 1)
             }
         }
 
@@ -1527,7 +1538,6 @@
                 id="virtual-list-items"
                 {...testId ? { 'data-testid': `${testId}-items` } : {}}
                 class={itemsClass ?? 'virtual-list-items'}
-                style:visibility={height === 0 && mode === 'bottomToTop' ? 'hidden' : 'visible'}
                 style:transform="translateY({(() => {
                     const viewportHeight = height || measuredFallbackHeight || 0
                     const visibleRange = visibleItems()

package/dist/utils/scrollCalculation.d.ts

@@ -1,4 +1,39 @@
 import type { SvelteVirtualListMode, SvelteVirtualListScrollAlign } from '../types.js';
+/**
+ * Calculates the scroll target for aligning an item to a specific edge.
+ *
+ * This helper consolidates the shared alignment logic between bottomToTop
+ * and topToBottom scroll calculations, reducing code duplication.
+ *
+ * @param {number} itemTop - The top position of the item in pixels
+ * @param {number} itemBottom - The bottom position of the item in pixels
+ * @param {number} scrollTop - Current scroll position in pixels
+ * @param {number} viewportHeight - Height of the viewport in pixels
+ * @param {'top' | 'bottom' | 'nearest'} align - The alignment mode
+ * @returns {number | null} The scroll target position, or null if item is already visible (for 'nearest')
+ */
+export declare const alignToEdge: (itemTop: number, itemBottom: number, scrollTop: number, viewportHeight: number, align: "top" | "bottom" | "nearest") => number | null;
+/**
+ * Calculates the scroll target for aligning a visible item to its nearest edge.
+ *
+ * Unlike alignToEdge with 'nearest', this always returns a scroll position
+ * even when the item is visible. Used for 'auto' alignment mode when item
+ * is within the visible range.
+ *
+ * @param {number} itemTop - The top position of the item in pixels
+ * @param {number} itemBottom - The bottom position of the item in pixels
+ * @param {number} scrollTop - Current scroll position in pixels
+ * @param {number} viewportHeight - Height of the viewport in pixels
+ * @returns {number} The scroll target position aligned to nearest edge
+ *
+ * @example
+ * ```typescript
+ * // For a visible item, align to whichever edge is closer
+ * const scrollTarget = alignVisibleToNearestEdge(400, 450, 200, 400)
+ * viewportElement.scrollTo({ top: scrollTarget })
+ * ```
+ */
+export declare const alignVisibleToNearestEdge: (itemTop: number, itemBottom: number, scrollTop: number, viewportHeight: number) => number;
 /**
  * Parameters for calculating scroll target position
  */

package/dist/utils/scrollCalculation.js

@@ -1,4 +1,66 @@
-import { getScrollOffsetForIndex } from './virtualList.js';
+import { clampValue, getScrollOffsetForIndex } from './virtualList.js';
+/**
+ * Calculates the scroll target for aligning an item to a specific edge.
+ *
+ * This helper consolidates the shared alignment logic between bottomToTop
+ * and topToBottom scroll calculations, reducing code duplication.
+ *
+ * @param {number} itemTop - The top position of the item in pixels
+ * @param {number} itemBottom - The bottom position of the item in pixels
+ * @param {number} scrollTop - Current scroll position in pixels
+ * @param {number} viewportHeight - Height of the viewport in pixels
+ * @param {'top' | 'bottom' | 'nearest'} align - The alignment mode
+ * @returns {number | null} The scroll target position, or null if item is already visible (for 'nearest')
+ */
+export const alignToEdge = (itemTop, itemBottom, scrollTop, viewportHeight, align) => {
+    if (align === 'top') {
+        return itemTop;
+    }
+    if (align === 'bottom') {
+        return clampValue(itemBottom - viewportHeight, 0, Infinity);
+    }
+    // 'nearest' alignment
+    const viewportBottom = scrollTop + viewportHeight;
+    const isVisible = itemTop < viewportBottom && itemBottom > scrollTop;
+    if (isVisible) {
+        // Already visible, no scroll needed
+        return null;
+    }
+    // Not visible - align to nearest edge
+    const distanceToTop = Math.abs(scrollTop - itemTop);
+    const distanceToBottom = Math.abs(viewportBottom - itemBottom);
+    return distanceToTop < distanceToBottom
+        ? itemTop
+        : clampValue(itemBottom - viewportHeight, 0, Infinity);
+};
+/**
+ * Calculates the scroll target for aligning a visible item to its nearest edge.
+ *
+ * Unlike alignToEdge with 'nearest', this always returns a scroll position
+ * even when the item is visible. Used for 'auto' alignment mode when item
+ * is within the visible range.
+ *
+ * @param {number} itemTop - The top position of the item in pixels
+ * @param {number} itemBottom - The bottom position of the item in pixels
+ * @param {number} scrollTop - Current scroll position in pixels
+ * @param {number} viewportHeight - Height of the viewport in pixels
+ * @returns {number} The scroll target position aligned to nearest edge
+ *
+ * @example
+ * ```typescript
+ * // For a visible item, align to whichever edge is closer
+ * const scrollTarget = alignVisibleToNearestEdge(400, 450, 200, 400)
+ * viewportElement.scrollTo({ top: scrollTarget })
+ * ```
+ */
+export const alignVisibleToNearestEdge = (itemTop, itemBottom, scrollTop, viewportHeight) => {
+    const viewportBottom = scrollTop + viewportHeight;
+    const distanceToTop = Math.abs(scrollTop - itemTop);
+    const distanceToBottom = Math.abs(viewportBottom - itemBottom);
+    return distanceToTop < distanceToBottom
+        ? itemTop
+        : clampValue(itemBottom - viewportHeight, 0, Infinity);
+};
 /**
  * Calculates the target scroll position for scrolling to a specific item index.
  *
@@ -74,42 +136,25 @@ const calculateBottomToTopScrollTarget = (params) => {
     const totalHeight = getScrollOffsetForIndex(heightCache, calculatedItemHeight, itemsLength);
     const itemOffset = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
     const itemHeight = calculatedItemHeight;
+    // Calculate item boundaries in bottomToTop coordinate space
+    const itemTop = totalHeight - (itemOffset + itemHeight);
+    const itemBottom = totalHeight - itemOffset;
     if (align === 'auto') {
         // If item is above the viewport, align to top
         if (targetIndex < firstVisibleIndex) {
-            return Math.max(0, totalHeight - (itemOffset + itemHeight));
+            return alignToEdge(itemTop, itemBottom, scrollTop, height, 'top');
         }
         else if (targetIndex > lastVisibleIndex - 1) {
             // In bottomToTop, "below" means higher indices that need HIGHER scrollTop
-            return Math.max(0, totalHeight - itemOffset - height);
+            return alignToEdge(itemTop, itemBottom, scrollTop, height, 'bottom');
         }
         else {
-            const itemTop = totalHeight - (itemOffset + itemHeight);
-            const itemBottom = totalHeight - itemOffset;
-            const distanceToTop = Math.abs(scrollTop - itemTop);
-            const distanceToBottom = Math.abs(scrollTop + height - itemBottom);
-            return distanceToTop < distanceToBottom ? itemTop : Math.max(0, itemBottom - height);
+            // Item is visible - align to nearest edge (always returns a value)
+            return alignVisibleToNearestEdge(itemTop, itemBottom, scrollTop, height);
         }
     }
-    else if (align === 'top') {
-        return Math.max(0, totalHeight - (itemOffset + itemHeight));
-    }
-    else if (align === 'bottom') {
-        return Math.max(0, totalHeight - itemOffset - height);
-    }
-    else if (align === 'nearest') {
-        const itemTop = totalHeight - (itemOffset + itemHeight);
-        const itemBottom = totalHeight - itemOffset;
-        if (itemBottom <= scrollTop || itemTop >= scrollTop + height) {
-            // Not visible, align to nearest edge
-            const distanceToTop = Math.abs(scrollTop - itemTop);
-            const distanceToBottom = Math.abs(scrollTop + height - itemBottom);
-            return distanceToTop < distanceToBottom ? itemTop : Math.max(0, itemBottom - height);
-        }
-        else {
-            // Already visible, do nothing
-            return null;
-        }
+    if (align === 'top' || align === 'bottom' || align === 'nearest') {
+        return alignToEdge(itemTop, itemBottom, scrollTop, height, align);
     }
     return null;
 };
@@ -126,58 +171,25 @@ const calculateBottomToTopScrollTarget = (params) => {
  */
 const calculateTopToBottomScrollTarget = (params) => {
     const { align, targetIndex, calculatedItemHeight, height, scrollTop, firstVisibleIndex, lastVisibleIndex, heightCache } = params;
+    // Calculate item boundaries
+    const itemTop = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
+    const itemBottom = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex + 1);
     if (align === 'auto') {
         // If item is above the viewport, align to top
         if (targetIndex < firstVisibleIndex) {
-            const scrollTarget = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
-            return scrollTarget;
+            return alignToEdge(itemTop, itemBottom, scrollTop, height, 'top');
         }
         // If item is below the viewport, align to bottom
         else if (targetIndex > lastVisibleIndex - 1) {
-            const itemBottom = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex + 1);
-            const scrollTarget = Math.max(0, itemBottom - height);
-            return scrollTarget;
+            return alignToEdge(itemTop, itemBottom, scrollTop, height, 'bottom');
         }
         else {
-            // Item is visible but not aligned: align to nearest edge
-            const itemTop = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
-            const itemBottom = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex + 1);
-            const distanceToTop = Math.abs(scrollTop - itemTop);
-            const distanceToBottom = Math.abs(scrollTop + height - itemBottom);
-            if (distanceToTop < distanceToBottom) {
-                return itemTop;
-            }
-            else {
-                return Math.max(0, itemBottom - height);
-            }
+            // Item is visible - align to nearest edge (always returns a value)
+            return alignVisibleToNearestEdge(itemTop, itemBottom, scrollTop, height);
         }
     }
-    else if (align === 'top') {
-        const scrollTarget = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
-        return scrollTarget;
-    }
-    else if (align === 'bottom') {
-        const itemBottom = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex + 1);
-        return Math.max(0, itemBottom - height);
-    }
-    else if (align === 'nearest') {
-        const itemTop = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
-        const itemBottom = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex + 1);
-        if (itemBottom <= scrollTop || itemTop >= scrollTop + height) {
-            // Not visible, align to nearest edge
-            const distanceToTop = Math.abs(scrollTop - itemTop);
-            const distanceToBottom = Math.abs(scrollTop + height - itemBottom);
-            if (distanceToTop < distanceToBottom) {
-                return itemTop;
-            }
-            else {
-                return Math.max(0, itemBottom - height);
-            }
-        }
-        else {
-            // Already visible, do nothing
-            return null;
-        }
+    if (align === 'top' || align === 'bottom' || align === 'nearest') {
+        return alignToEdge(itemTop, itemBottom, scrollTop, height, align);
     }
     return null;
 };

package/dist/utils/virtualList.d.ts

@@ -1,5 +1,41 @@
 import type { SvelteVirtualListMode, SvelteVirtualListPreviousVisibleRange } from '../types.js';
 import type { VirtualListSetters, VirtualListState } from './types.js';
+/**
+ * Validates a height value and returns it if valid, otherwise returns the fallback.
+ *
+ * A height is considered valid if it is a finite number greater than 0.
+ * This utility consolidates the repeated pattern of height validation
+ * found throughout the virtual list codebase.
+ *
+ * @param {unknown} height - The height value to validate
+ * @param {number} fallback - The fallback value to use if height is invalid
+ * @returns {number} The validated height or the fallback value
+ *
+ * @example
+ * ```typescript
+ * const height = getValidHeight(heightCache[i], calculatedItemHeight)
+ * // Returns heightCache[i] if valid, otherwise calculatedItemHeight
+ * ```
+ */
+export declare const getValidHeight: (height: unknown, fallback: number) => number;
+/**
+ * Clamps a numeric value to be within a specified range.
+ *
+ * This utility consolidates the repeated `Math.max(min, Math.min(max, value))`
+ * pattern used throughout scroll calculations and positioning logic.
+ *
+ * @param {number} value - The value to clamp
+ * @param {number} min - The minimum allowed value
+ * @param {number} max - The maximum allowed value
+ * @returns {number} The clamped value
+ *
+ * @example
+ * ```typescript
+ * const scrollTop = clampValue(targetScrollTop, 0, maxScrollTop)
+ * // Ensures scrollTop is between 0 and maxScrollTop
+ * ```
+ */
+export declare const clampValue: (value: number, min: number, max: number) => number;
 /**
  * Calculates the maximum scroll position for a virtual list.
  *

package/dist/utils/virtualList.js

@@ -1,3 +1,39 @@
+/**
+ * Validates a height value and returns it if valid, otherwise returns the fallback.
+ *
+ * A height is considered valid if it is a finite number greater than 0.
+ * This utility consolidates the repeated pattern of height validation
+ * found throughout the virtual list codebase.
+ *
+ * @param {unknown} height - The height value to validate
+ * @param {number} fallback - The fallback value to use if height is invalid
+ * @returns {number} The validated height or the fallback value
+ *
+ * @example
+ * ```typescript
+ * const height = getValidHeight(heightCache[i], calculatedItemHeight)
+ * // Returns heightCache[i] if valid, otherwise calculatedItemHeight
+ * ```
+ */
+export const getValidHeight = (height, fallback) => Number.isFinite(height) && height > 0 ? height : fallback;
+/**
+ * Clamps a numeric value to be within a specified range.
+ *
+ * This utility consolidates the repeated `Math.max(min, Math.min(max, value))`
+ * pattern used throughout scroll calculations and positioning logic.
+ *
+ * @param {number} value - The value to clamp
+ * @param {number} min - The minimum allowed value
+ * @param {number} max - The maximum allowed value
+ * @returns {number} The clamped value
+ *
+ * @example
+ * ```typescript
+ * const scrollTop = clampValue(targetScrollTop, 0, maxScrollTop)
+ * // Ensures scrollTop is between 0 and maxScrollTop
+ * ```
+ */
+export const clampValue = (value, min, max) => Math.max(min, Math.min(max, value));
 /**
  * Calculates the maximum scroll position for a virtual list.
  *
@@ -68,10 +104,7 @@ export const calculateVisibleRange = (scrollTop, viewportHeight, itemHeight, tot
             const adjustedEnd = totalItems;
             let startCore = adjustedEnd;
             let acc = 0;
-            const getH = (i) => {
-                const v = heightCache ? heightCache[i] : undefined;
-                return Number.isFinite(v) && v > 0 ? v : itemHeight;
-            };
+            const getH = (i) => getValidHeight(heightCache ? heightCache[i] : undefined, itemHeight);
             while (startCore > 0 && acc < viewportHeight) {
                 const h = getH(startCore - 1);
                 acc += h;
@@ -366,9 +399,7 @@ export const getScrollOffsetForIndex = (heightCache, calculatedItemHeight, idx,
         // Fallback: O(n) for a single query
         let offset = 0;
         for (let i = 0; i < safeIdx; i++) {
-            const raw = heightCache[i];
-            const height = Number.isFinite(raw) && raw > 0 ? raw : calculatedItemHeight;
-            offset += height;
+            offset += getValidHeight(heightCache[i], calculatedItemHeight);
         }
         return offset;
     }
@@ -381,9 +412,7 @@ export const getScrollOffsetForIndex = (heightCache, calculatedItemHeight, idx,
     let offset = offsetBase;
     const start = blockIdx * blockSize;
     for (let i = start; i < safeIdx; i++) {
-        const raw = heightCache[i];
-        const height = Number.isFinite(raw) && raw > 0 ? raw : calculatedItemHeight;
-        offset += height;
+        offset += getValidHeight(heightCache[i], calculatedItemHeight);
     }
     return offset;
 };
@@ -422,9 +451,7 @@ export const buildBlockSums = (heightCache, calculatedItemHeight, totalItems, bl
         const start = b * blockSize;
         const end = start + blockSize;
         for (let i = start; i < end; i++) {
-            const raw = heightCache[i];
-            const h = Number.isFinite(raw) && raw > 0 ? raw : calculatedItemHeight;
-            running += h;
+            running += getValidHeight(heightCache[i], calculatedItemHeight);
         }
         sums[b] = running;
     }

package/package.json

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