@humanspeak/svelte-virtual-list 0.3.6 → 0.3.9

package/dist/SvelteVirtualList.svelte.d.ts

@@ -92,6 +92,26 @@ import { type SvelteVirtualListProps, type SvelteVirtualListScrollOptions } from
 declare function $$render<TItem = unknown>(): {
     props: SvelteVirtualListProps<TItem>;
     exports: {
+        /**
+             * Runs a batch of updates with scroll corrections coalesced until the batch completes.
+             *
+             * Use this method when making multiple changes to the items array to prevent
+             * intermediate scroll corrections. The scroll position reconciliation is deferred
+             * until the batch exits, ensuring smooth visual updates.
+             *
+             * @param {() => void} fn - The function containing batch updates to execute.
+             * @returns {void}
+             *
+             * @example
+             * ```typescript
+             * // Add multiple items without intermediate scroll corrections
+             * list.runInBatch(() => {
+             *     items.push(newItem1);
+             *     items.push(newItem2);
+             *     items.push(newItem3);
+             * });
+             * ```
+             */ runInBatch: (fn: () => void) => void;
         /**
              * Scrolls the virtual list to the item at the given index.
              *
@@ -159,6 +179,26 @@ declare class __sveltets_Render<TItem = unknown> {
     slots(): ReturnType<typeof $$render<TItem>>['slots'];
     bindings(): "";
     exports(): {
+        /**
+             * Runs a batch of updates with scroll corrections coalesced until the batch completes.
+             *
+             * Use this method when making multiple changes to the items array to prevent
+             * intermediate scroll corrections. The scroll position reconciliation is deferred
+             * until the batch exits, ensuring smooth visual updates.
+             *
+             * @param {() => void} fn - The function containing batch updates to execute.
+             * @returns {void}
+             *
+             * @example
+             * ```typescript
+             * // Add multiple items without intermediate scroll corrections
+             * list.runInBatch(() => {
+             *     items.push(newItem1);
+             *     items.push(newItem2);
+             *     items.push(newItem3);
+             * });
+             * ```
+             */ runInBatch: (fn: () => void) => void;
         /**
              * Scrolls the virtual list to the item at the given index.
              *

package/dist/reactive-list-manager/RecomputeScheduler.d.ts

@@ -1,13 +1,91 @@
+/**
+ * Scheduler that coalesces recompute requests to the next animation frame.
+ *
+ * This class provides efficient batching of recompute operations by scheduling
+ * them to run on the next animation frame in browser environments. In non-browser
+ * or jsdom environments, it falls back to setTimeout(0) for deterministic testing.
+ *
+ * Key features:
+ * - Coalesces multiple schedule() calls into a single recompute
+ * - Supports temporary blocking during critical sections
+ * - Handles nested block/unblock calls with depth tracking
+ * - Environment-aware: uses RAF in browsers, setTimeout in tests
+ *
+ * @example
+ * ```typescript
+ * const scheduler = new RecomputeScheduler(() => {
+ *     console.log('Recomputing derived state');
+ * });
+ *
+ * // Multiple calls within the same frame are coalesced
+ * scheduler.schedule();
+ * scheduler.schedule();
+ * scheduler.schedule(); // Only one recompute will run
+ *
+ * // Block during critical sections
+ * scheduler.block();
+ * scheduler.schedule(); // Marked as pending, won't run yet
+ * scheduler.unblock();  // Runs immediately if pending
+ * ```
+ *
+ * @class
+ */
 export declare class RecomputeScheduler {
+    /** Callback function to execute on recompute. */
     private onRecompute;
+    /** Whether a recompute is currently scheduled. */
     private isScheduled;
+    /** Whether a recompute is pending due to blocking. */
     private isPending;
+    /** Current nesting depth of block() calls. */
     private blockDepth;
+    /** ID of the pending setTimeout (non-browser fallback). */
     private timeoutId;
+    /** ID of the pending requestAnimationFrame. */
     private rafId;
+    /**
+     * Creates a new RecomputeScheduler instance.
+     *
+     * @param {() => void} onRecompute - Callback function to execute when recompute runs.
+     */
     constructor(onRecompute: () => void);
+    /**
+     * Schedules a recompute for the next animation frame.
+     *
+     * If the scheduler is blocked, the request is marked as pending and will
+     * execute when unblocked. Multiple calls while a recompute is already
+     * scheduled are coalesced into a single execution.
+     *
+     * @returns {void}
+     */
     schedule: () => void;
+    /**
+     * Temporarily blocks recompute execution.
+     *
+     * Cancels any in-flight timers and marks any pending recompute request.
+     * Block calls can be nested; the scheduler remains blocked until all
+     * corresponding unblock() calls are made.
+     *
+     * @returns {void}
+     */
     block: () => void;
+    /**
+     * Unblocks the scheduler and runs pending recompute if any.
+     *
+     * Decrements the block depth counter. When the depth reaches zero and
+     * a recompute was pending, it executes immediately (synchronously).
+     * Guards against underflow if unblock is called without matching block.
+     *
+     * @returns {void}
+     */
     unblock: () => void;
+    /**
+     * Cancels any scheduled or pending recompute.
+     *
+     * Clears all timers (setTimeout and RAF) and resets the scheduled
+     * and pending flags. Does not affect the block depth.
+     *
+     * @returns {void}
+     */
     cancel: () => void;
 }

package/dist/reactive-list-manager/RecomputeScheduler.js

@@ -1,19 +1,65 @@
-// RecomputeScheduler
-// -------------------
-// Coalesces recompute requests to the next animation frame in the browser.
-// Falls back to setTimeout(0) in non-browser/jsdom to preserve deterministic tests.
-// Supports temporary blocking to delay recomputation during critical sections.
+/**
+ * Scheduler that coalesces recompute requests to the next animation frame.
+ *
+ * This class provides efficient batching of recompute operations by scheduling
+ * them to run on the next animation frame in browser environments. In non-browser
+ * or jsdom environments, it falls back to setTimeout(0) for deterministic testing.
+ *
+ * Key features:
+ * - Coalesces multiple schedule() calls into a single recompute
+ * - Supports temporary blocking during critical sections
+ * - Handles nested block/unblock calls with depth tracking
+ * - Environment-aware: uses RAF in browsers, setTimeout in tests
+ *
+ * @example
+ * ```typescript
+ * const scheduler = new RecomputeScheduler(() => {
+ *     console.log('Recomputing derived state');
+ * });
+ *
+ * // Multiple calls within the same frame are coalesced
+ * scheduler.schedule();
+ * scheduler.schedule();
+ * scheduler.schedule(); // Only one recompute will run
+ *
+ * // Block during critical sections
+ * scheduler.block();
+ * scheduler.schedule(); // Marked as pending, won't run yet
+ * scheduler.unblock();  // Runs immediately if pending
+ * ```
+ *
+ * @class
+ */
 export class RecomputeScheduler {
+    /** Callback function to execute on recompute. */
     onRecompute;
+    /** Whether a recompute is currently scheduled. */
     isScheduled = false;
+    /** Whether a recompute is pending due to blocking. */
     isPending = false;
+    /** Current nesting depth of block() calls. */
     blockDepth = 0;
+    /** ID of the pending setTimeout (non-browser fallback). */
     timeoutId = null;
+    /** ID of the pending requestAnimationFrame. */
     rafId = null;
+    /**
+     * Creates a new RecomputeScheduler instance.
+     *
+     * @param {() => void} onRecompute - Callback function to execute when recompute runs.
+     */
     constructor(onRecompute) {
         this.onRecompute = onRecompute;
     }
-    // Request a recompute. If blocked, mark as pending; otherwise schedule for next frame.
+    /**
+     * Schedules a recompute for the next animation frame.
+     *
+     * If the scheduler is blocked, the request is marked as pending and will
+     * execute when unblocked. Multiple calls while a recompute is already
+     * scheduled are coalesced into a single execution.
+     *
+     * @returns {void}
+     */
     schedule = () => {
         if (this.blockDepth > 0) {
             this.isPending = true;
@@ -45,7 +91,15 @@ export class RecomputeScheduler {
             this.onRecompute();
         });
     };
-    // Temporarily block recomputes; any in-flight timers are canceled and a recompute is marked pending.
+    /**
+     * Temporarily blocks recompute execution.
+     *
+     * Cancels any in-flight timers and marks any pending recompute request.
+     * Block calls can be nested; the scheduler remains blocked until all
+     * corresponding unblock() calls are made.
+     *
+     * @returns {void}
+     */
     block = () => {
         this.blockDepth += 1;
         if (this.timeoutId) {
@@ -61,7 +115,15 @@ export class RecomputeScheduler {
             this.isPending = true;
         }
     };
-    // Unblock and run recompute immediately if one was pending.
+    /**
+     * Unblocks the scheduler and runs pending recompute if any.
+     *
+     * Decrements the block depth counter. When the depth reaches zero and
+     * a recompute was pending, it executes immediately (synchronously).
+     * Guards against underflow if unblock is called without matching block.
+     *
+     * @returns {void}
+     */
     unblock = () => {
         if (this.blockDepth === 0)
             return;
@@ -71,7 +133,14 @@ export class RecomputeScheduler {
             this.onRecompute();
         }
     };
-    // Cancel any scheduled recompute and clear pending state.
+    /**
+     * Cancels any scheduled or pending recompute.
+     *
+     * Clears all timers (setTimeout and RAF) and resets the scheduled
+     * and pending flags. Does not affect the block depth.
+     *
+     * @returns {void}
+     */
     cancel = () => {
         if (this.timeoutId) {
             clearTimeout(this.timeoutId);

package/dist/types.d.ts

@@ -63,6 +63,21 @@ export type SvelteVirtualListProps<TItem = any> = {
      * CSS class to apply to the scrollable viewport element.
      */
     viewportClass?: string;
+    /**
+     * Callback when more data is needed. Supports sync and async functions.
+     * Called when the user scrolls near the end of the list (based on loadMoreThreshold).
+     */
+    onLoadMore?: () => void | Promise<void>;
+    /**
+     * Number of items from the end to trigger onLoadMore.
+     * @default 20
+     */
+    loadMoreThreshold?: number;
+    /**
+     * Set to false when all data has been loaded to stop triggering onLoadMore.
+     * @default true
+     */
+    hasMore?: boolean;
 };
 /**
  * Debug information provided by the virtual list during rendering.

package/dist/utils/heightChangeDetection.d.ts

@@ -1,12 +1,37 @@
 /**
- * Utility functions for detecting significant height changes in virtual list items
+ * Utility functions for detecting significant height changes in virtual list items.
+ *
+ * @fileoverview Provides height change detection utilities for virtual list optimization.
+ * These functions help determine when item height changes are significant enough to
+ * trigger recalculations, preventing unnecessary updates for sub-pixel variations.
  */
 /**
- * Checks if a height change is significant enough to warrant marking an item as dirty
- * @param itemIndex - The index of the item
- * @param newHeight - The new measured height
- * @param heightCache - Existing height cache to compare against
- * @param marginOfError - Height difference threshold (default: 1px)
- * @returns true if the height change is significant
+ * Checks if a height change is significant enough to warrant marking an item as dirty.
+ *
+ * This function compares the new measured height against the cached height for an item
+ * and determines if the difference exceeds the specified margin of error. Items with
+ * no previous measurement are always considered significant.
+ *
+ * @param {number} itemIndex - The index of the item in the virtual list.
+ * @param {number} newHeight - The new measured height in pixels.
+ * @param {Record<number, number>} heightCache - Cache of previously measured item heights.
+ * @param {number} [marginOfError=1] - Height difference threshold in pixels. Changes
+ *     smaller than this value are considered insignificant.
+ * @returns {boolean} Returns true if the height change exceeds the margin of error
+ *     or if this is the first measurement for the item.
+ *
+ * @example
+ * ```typescript
+ * const heightCache = { 0: 40, 1: 50 };
+ *
+ * // First-time measurement (no cache entry)
+ * isSignificantHeightChange(2, 45, heightCache); // true
+ *
+ * // Significant change (exceeds 1px threshold)
+ * isSignificantHeightChange(0, 45, heightCache); // true
+ *
+ * // Insignificant change (within 1px threshold)
+ * isSignificantHeightChange(0, 40.5, heightCache); // false
+ * ```
  */
 export declare const isSignificantHeightChange: (itemIndex: number, newHeight: number, heightCache: Record<number, number>, marginOfError?: number) => boolean;

package/dist/utils/heightChangeDetection.js

@@ -1,13 +1,38 @@
 /**
- * Utility functions for detecting significant height changes in virtual list items
+ * Utility functions for detecting significant height changes in virtual list items.
+ *
+ * @fileoverview Provides height change detection utilities for virtual list optimization.
+ * These functions help determine when item height changes are significant enough to
+ * trigger recalculations, preventing unnecessary updates for sub-pixel variations.
  */
 /**
- * Checks if a height change is significant enough to warrant marking an item as dirty
- * @param itemIndex - The index of the item
- * @param newHeight - The new measured height
- * @param heightCache - Existing height cache to compare against
- * @param marginOfError - Height difference threshold (default: 1px)
- * @returns true if the height change is significant
+ * Checks if a height change is significant enough to warrant marking an item as dirty.
+ *
+ * This function compares the new measured height against the cached height for an item
+ * and determines if the difference exceeds the specified margin of error. Items with
+ * no previous measurement are always considered significant.
+ *
+ * @param {number} itemIndex - The index of the item in the virtual list.
+ * @param {number} newHeight - The new measured height in pixels.
+ * @param {Record<number, number>} heightCache - Cache of previously measured item heights.
+ * @param {number} [marginOfError=1] - Height difference threshold in pixels. Changes
+ *     smaller than this value are considered insignificant.
+ * @returns {boolean} Returns true if the height change exceeds the margin of error
+ *     or if this is the first measurement for the item.
+ *
+ * @example
+ * ```typescript
+ * const heightCache = { 0: 40, 1: 50 };
+ *
+ * // First-time measurement (no cache entry)
+ * isSignificantHeightChange(2, 45, heightCache); // true
+ *
+ * // Significant change (exceeds 1px threshold)
+ * isSignificantHeightChange(0, 45, heightCache); // true
+ *
+ * // Insignificant change (within 1px threshold)
+ * isSignificantHeightChange(0, 40.5, heightCache); // false
+ * ```
  */
 export const isSignificantHeightChange = (itemIndex, newHeight, heightCache, marginOfError = 1) => {
     const previousHeight = heightCache[itemIndex];

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.
  *
@@ -58,7 +120,15 @@ export const calculateScrollTarget = (params) => {
     }
 };
 /**
- * Calculates scroll target for bottom-to-top mode
+ * Calculates the target scroll position for bottom-to-top mode.
+ *
+ * In bottom-to-top mode, items are rendered from the bottom of the viewport upward,
+ * which requires different scroll calculations than the standard top-to-bottom mode.
+ * This function handles the coordinate system translation and alignment logic.
+ *
+ * @param {BottomToTopScrollParams} params - Parameters for scroll calculation.
+ * @returns {number | null} The target scroll position in pixels, or null if no
+ *     scroll is needed (item already visible with 'nearest' alignment).
  */
 const calculateBottomToTopScrollTarget = (params) => {
     const { align, targetIndex, itemsLength, calculatedItemHeight, height, scrollTop, firstVisibleIndex, lastVisibleIndex, heightCache } = params;
@@ -66,102 +136,60 @@ 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;
 };
 /**
- * Calculates scroll target for top-to-bottom mode
+ * Calculates the target scroll position for top-to-bottom mode.
+ *
+ * This is the standard scroll mode where items are rendered from the top of the
+ * viewport downward. The function calculates the optimal scroll position based
+ * on the alignment option and current viewport state.
+ *
+ * @param {TopToBottomScrollParams} params - Parameters for scroll calculation.
+ * @returns {number | null} The target scroll position in pixels, or null if no
+ *     scroll is needed (item already visible with 'nearest' alignment).
  */
 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;
 };