@humanspeak/svelte-virtual-list 0.4.6 → 0.5.1

package/dist/SvelteVirtualList.svelte.d.ts

@@ -12,49 +12,44 @@
      *    - Implemented debounced measurements
      *    - Created height averaging mechanism for performance
      *
-     * 3. Bidirectional Scrolling ✓
-     *    - Added bottomToTop mode
-     *    - Solved complex initialization issues with flexbox
-     *    - Implemented careful scroll position management
-     *
-     * 4. Performance Optimizations ✓
+     * 3. Performance Optimizations ✓
      *    - Added element recycling through keyed each blocks
      *    - Implemented RAF for smooth animations
      *    - Optimized DOM updates with transform translations
      *
-     * 5. Stability Improvements ✓
+     * 4. Stability Improvements ✓
      *    - Added ResizeObserver for responsive updates
      *    - Implemented proper cleanup on component destruction
      *    - Added debug mode for development assistance
      *
-     * 6. Large Dataset Optimizations ✓
+     * 5. Large Dataset Optimizations ✓
      *    - Implemented chunked processing for 10k+ items
      *    - Added progressive initialization system
      *    - Deferred height calculations for better initial load
      *    - Optimized memory usage for large lists
      *    - Added progress tracking for initialization
      *
-     * 7. Size Management Improvements ✓
+     * 6. Size Management Improvements ✓
      *    - Implemented height caching system for measured items
      *    - Added smart height estimation for unmeasured items
      *    - Optimized resize handling with debouncing
      *    - Added height recalculation on content changes
      *    - Implemented progressive height adjustments
      *
-     * 8. Code Quality & Maintainability ✓
+     * 7. Code Quality & Maintainability ✓
      *    - Extracted debug utilities for better testing
      *    - Improved type safety throughout
      *    - Added comprehensive documentation
      *    - Optimized debug output to reduce noise
      *
-     * 9. Architecture Refactoring ✓
+     * 8. Architecture Refactoring ✓
      *    - Extracted scroll calculation logic to scrollCalculation.ts utility
      *    - Extracted ResizeObserver utilities to resizeObserver.ts
      *    - Added comprehensive test coverage for extracted utilities
      *    - Improved separation of concerns and maintainability
      *    - Simplified initialization (removed unnecessary chunked processing)
      *
-     * 10. Future Improvements (Planned)
+     * 9. Future Improvements (Planned)
      *    - Add horizontal scrolling support
      *    - Implement variable-sized item caching
      *    - Add keyboard navigation support
@@ -62,7 +57,6 @@
      *    - Add accessibility enhancements
      *
      * Technical Challenges Solved:
-     * - Bottom-to-top scrolling in flexbox layouts
      * - Dynamic height calculations without layout thrashing
      * - Smooth scrolling on various devices
      * - Memory management for large lists
@@ -92,26 +86,6 @@ 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.
              *
@@ -179,26 +153,6 @@ 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.
              *
@@ -268,14 +222,13 @@ interface $$IsomorphicComponent {
  * SvelteVirtualList
  *
  * A high-performance, memory-efficient virtualized list component for Svelte 5.
- * Renders only visible items plus a buffer, supporting dynamic item heights,
- * bi-directional (top-to-bottom and bottom-to-top) scrolling, and programmatic control.
+ * Renders only visible items plus a buffer, supporting dynamic item heights
+ * and programmatic control.
  *
  * =============================
  * ==  Key Features           ==
  * =============================
  * - Dynamic item height support (no fixed height required)
- * - Top-to-bottom and bottom-to-top (chat-style) scrolling
  * - Programmatic scrolling with flexible alignment (top, bottom, auto)
  * - Smooth scrolling and buffer size configuration
  * - SSR compatible and hydration-friendly
@@ -291,7 +244,6 @@ interface $$IsomorphicComponent {
  * ```svelte
  * <SvelteVirtualList
  *     items={data}
- *     mode="bottomToTop"
  *     bind:this={listRef}
  * >
  *     {#snippet renderItem(item)}
@@ -309,7 +261,6 @@ interface $$IsomorphicComponent {
  * - Handles resize events and dynamic content changes
  * - Optimized for very large lists through virtualization
  * - Modular architecture with extracted utility functions
- * - Bi-directional support: mode="topToBottom" or "bottomToTop"
  * - Designed for extensibility and easy debugging
  *
  * =============================

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import SvelteVirtualList from './SvelteVirtualList.svelte';
-import type { SvelteVirtualListDebugInfo, SvelteVirtualListMode, SvelteVirtualListProps, SvelteVirtualListScrollAlign, SvelteVirtualListScrollOptions } from './types.js';
-export type { SvelteVirtualListDebugInfo, SvelteVirtualListMode, SvelteVirtualListProps, SvelteVirtualListScrollAlign, SvelteVirtualListScrollOptions };
+import type { SvelteVirtualListDebugInfo, SvelteVirtualListProps, SvelteVirtualListScrollAlign, SvelteVirtualListScrollOptions } from './types.js';
+export type { SvelteVirtualListDebugInfo, SvelteVirtualListProps, SvelteVirtualListScrollAlign, SvelteVirtualListScrollOptions };
 export { ReactiveListManager } from './reactive-list-manager/index.js';
 export type { ListManagerConfig } from './reactive-list-manager/index.js';
 export { formatBytes, getCurrentFps, getMemoryUsage, isPerfEnabled, measureAsync, measureSync, perfMetrics, recordDuration, startFpsTracking, startMeasure, stopFpsTracking } from './utils/perfMetrics.js';

package/dist/reactive-list-manager/INTEGRATION_EXAMPLE.md

@@ -56,11 +56,6 @@ const updateHeight = () => {
             // }))
             // heightManager.processDirtyHeights(heightChanges)
 
-            // Handle scroll correction (bottomToTop mode)
-            if (result.heightChanges.length > 0 && mode === 'bottomToTop') {
-                handleHeightChangesScrollCorrection(result.heightChanges)
-            }
-
             // ... rest of callback logic
         }
     )

package/dist/types.d.ts

@@ -1,10 +1,4 @@
 import type { Snippet } from 'svelte';
-/**
- * Defines the scroll direction and rendering mode for the virtual list.
- *
- * @typedef {'topToBottom' | 'bottomToTop'} SvelteVirtualListMode
- */
-export type SvelteVirtualListMode = 'topToBottom' | 'bottomToTop';
 /**
  * Configuration properties for the SvelteVirtualList component.
  *
@@ -46,11 +40,6 @@ export type SvelteVirtualListProps<TItem = any> = {
      * CSS class to apply to individual item containers.
      */
     itemsClass?: string;
-    /**
-     * Determines the scroll and render direction.
-     * @default 'topToBottom'
-     */
-    mode?: SvelteVirtualListMode;
     /**
      * Svelte snippet function that defines how each item should be rendered. Receives the item and its index as arguments.
      */

package/dist/utils/heightCalculation.d.ts

@@ -1,4 +1,3 @@
-import type { SvelteVirtualListMode } from '../types.js';
 /**
  * Calculates and updates the average height of visible items with debouncing.
  *
@@ -84,4 +83,4 @@ export declare const calculateAverageHeightDebounced: (isCalculatingHeight: bool
         newHeight: number;
         delta: number;
     }>;
-}) => void, debounceTime: number, dirtyItems: Set<number>, currentTotalHeight?: number, currentValidCount?: number, mode?: SvelteVirtualListMode) => NodeJS.Timeout | null;
+}) => void, debounceTime: number, dirtyItems: Set<number>, currentTotalHeight?: number, currentValidCount?: number) => NodeJS.Timeout | null;

package/dist/utils/heightCalculation.js

@@ -71,7 +71,7 @@ import { BROWSER } from 'esm-env';
  */
 export const calculateAverageHeightDebounced = (isCalculatingHeight, heightUpdateTimeout, visibleItems, itemElements, heightCache, lastMeasuredIndex, calculatedItemHeight, 
 /* trunk-ignore(eslint/no-unused-vars) */
-onUpdate, debounceTime, dirtyItems, currentTotalHeight = 0, currentValidCount = 0, mode = 'topToBottom') => {
+onUpdate, debounceTime, dirtyItems, currentTotalHeight = 0, currentValidCount = 0) => {
     if (!BROWSER || isCalculatingHeight)
         return null;
     const currentIndex = visibleItems.start;
@@ -80,7 +80,7 @@ onUpdate, debounceTime, dirtyItems, currentTotalHeight = 0, currentValidCount =
     if (heightUpdateTimeout)
         clearTimeout(heightUpdateTimeout);
     return setTimeout(() => {
-        const { newHeight, newLastMeasuredIndex, updatedHeightCache, clearedDirtyItems, newTotalHeight, newValidCount, heightChanges } = calculateAverageHeight(itemElements, visibleItems, heightCache, calculatedItemHeight, dirtyItems, currentTotalHeight, currentValidCount, mode);
+        const { newHeight, newLastMeasuredIndex, updatedHeightCache, clearedDirtyItems, newTotalHeight, newValidCount, heightChanges } = calculateAverageHeight(itemElements, visibleItems, heightCache, calculatedItemHeight, dirtyItems, currentTotalHeight, currentValidCount);
         if (Math.abs(newHeight - calculatedItemHeight) > 1 || dirtyItems.size > 0) {
             onUpdate({
                 newHeight,

package/dist/utils/scrollCalculation.d.ts

@@ -1,10 +1,7 @@
-import type { SvelteVirtualListMode, SvelteVirtualListScrollAlign } from '../types.js';
+import type { 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
@@ -38,7 +35,6 @@ export declare const alignVisibleToNearestEdge: (itemTop: number, itemBottom: nu
  * Parameters for calculating scroll target position
  */
 export interface ScrollTargetParams {
-    mode: SvelteVirtualListMode;
     align: SvelteVirtualListScrollAlign;
     targetIndex: number;
     itemsLength: number;
@@ -52,9 +48,8 @@ export interface ScrollTargetParams {
 /**
  * Calculates the target scroll position for scrolling to a specific item index.
  *
- * This function handles both topToBottom and bottomToTop scroll modes with different
- * alignment options (auto, top, bottom, nearest). It takes into account the current
- * viewport state and calculates the optimal scroll position.
+ * This function handles different alignment options (auto, top, bottom, nearest)
+ * and calculates the optimal scroll position based on the current viewport state.
  *
  * @param params - Parameters for scroll target calculation
  * @returns The target scroll position in pixels, or null if no scroll is needed
@@ -62,7 +57,6 @@ export interface ScrollTargetParams {
  * @example
  * ```typescript
  * const scrollTarget = calculateScrollTarget({
- *     mode: 'topToBottom',
  *     align: 'auto',
  *     targetIndex: 100,
  *     itemsLength: 1000,

package/dist/utils/scrollCalculation.js

@@ -2,9 +2,6 @@ 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
@@ -64,9 +61,8 @@ export const alignVisibleToNearestEdge = (itemTop, itemBottom, scrollTop, viewpo
 /**
  * Calculates the target scroll position for scrolling to a specific item index.
  *
- * This function handles both topToBottom and bottomToTop scroll modes with different
- * alignment options (auto, top, bottom, nearest). It takes into account the current
- * viewport state and calculates the optimal scroll position.
+ * This function handles different alignment options (auto, top, bottom, nearest)
+ * and calculates the optimal scroll position based on the current viewport state.
  *
  * @param params - Parameters for scroll target calculation
  * @returns The target scroll position in pixels, or null if no scroll is needed
@@ -74,7 +70,6 @@ export const alignVisibleToNearestEdge = (itemTop, itemBottom, scrollTop, viewpo
  * @example
  * ```typescript
  * const scrollTarget = calculateScrollTarget({
- *     mode: 'topToBottom',
  *     align: 'auto',
  *     targetIndex: 100,
  *     itemsLength: 1000,
@@ -92,71 +87,17 @@ export const alignVisibleToNearestEdge = (itemTop, itemBottom, scrollTop, viewpo
  * ```
  */
 export const calculateScrollTarget = (params) => {
-    const { mode, align, targetIndex, itemsLength, calculatedItemHeight, height, scrollTop, firstVisibleIndex, lastVisibleIndex, heightCache } = params;
-    if (mode === 'bottomToTop') {
-        return calculateBottomToTopScrollTarget({
-            align,
-            targetIndex,
-            itemsLength,
-            calculatedItemHeight,
-            height,
-            scrollTop,
-            firstVisibleIndex,
-            lastVisibleIndex,
-            heightCache
-        });
-    }
-    else {
-        return calculateTopToBottomScrollTarget({
-            align,
-            targetIndex,
-            calculatedItemHeight,
-            height,
-            scrollTop,
-            firstVisibleIndex,
-            lastVisibleIndex,
-            heightCache
-        });
-    }
-};
-/**
- * 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;
-    // Use getScrollOffsetForIndex for accurate positioning with height cache
-    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 alignToEdge(itemTop, itemBottom, scrollTop, height, 'top');
-        }
-        else if (targetIndex > lastVisibleIndex - 1) {
-            // In bottomToTop, "below" means higher indices that need HIGHER scrollTop
-            return alignToEdge(itemTop, itemBottom, scrollTop, height, 'bottom');
-        }
-        else {
-            // Item is visible - align to nearest edge (always returns a value)
-            return alignVisibleToNearestEdge(itemTop, itemBottom, scrollTop, height);
-        }
-    }
-    if (align === 'top' || align === 'bottom' || align === 'nearest') {
-        return alignToEdge(itemTop, itemBottom, scrollTop, height, align);
-    }
-    return null;
+    const { align, targetIndex, calculatedItemHeight, height, scrollTop, firstVisibleIndex, lastVisibleIndex, heightCache } = params;
+    return calculateTopToBottomScrollTarget({
+        align,
+        targetIndex,
+        calculatedItemHeight,
+        height,
+        scrollTop,
+        firstVisibleIndex,
+        lastVisibleIndex,
+        heightCache
+    });
 };
 /**
  * Calculates the target scroll position for top-to-bottom mode.

package/dist/utils/types.d.ts

@@ -1,4 +1,3 @@
-import type { SvelteVirtualListMode } from '../types.js';
 /**
  * Represents the internal state of a virtual list component.
  *
@@ -7,7 +6,6 @@ import type { SvelteVirtualListMode } from '../types.js';
  * the DOM elements involved and the current scroll metrics.
  *
  * @property {boolean} initialized - Indicates whether the virtual list has completed its initial setup
- * @property {SvelteVirtualListMode} mode - Defines the scrolling behavior ('topToBottom' or 'bottomToTop')
  * @property {HTMLElement | null} containerElement - Reference to the outer container DOM element
  * @property {HTMLElement | null} viewportElement - Reference to the viewport DOM element that clips visible content
  * @property {number} calculatedItemHeight - The computed height of each list item in pixels
@@ -16,7 +14,6 @@ import type { SvelteVirtualListMode } from '../types.js';
  */
 export type VirtualListState = {
     initialized: boolean;
-    mode: SvelteVirtualListMode;
     containerElement: HTMLElement | null;
     viewportElement: HTMLElement | null;
     calculatedItemHeight: number;

package/dist/utils/virtualList.d.ts

@@ -1,4 +1,4 @@
-import type { SvelteVirtualListMode, SvelteVirtualListPreviousVisibleRange } from '../types.js';
+import type { SvelteVirtualListPreviousVisibleRange } from '../types.js';
 import type { VirtualListSetters, VirtualListState } from './types.js';
 /**
  * Validates a height value and returns it if valid, otherwise returns the fallback.
@@ -58,17 +58,16 @@ export interface VisibleRangeOptions {
     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. */
+    /** Measured item heights keyed by index; used 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.
  *
- * 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
+ * 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 options - Inputs used to compute the visible range (see {@link VisibleRangeOptions}).
@@ -81,36 +80,31 @@ export interface VisibleRangeOptions {
  *     viewportHeight: 400,
  *     itemHeight: 40,
  *     totalItems: 1000,
- *     bufferSize: 2,
- *     mode: 'topToBottom'
+ *     bufferSize: 2
  * })
  * // range => { start: 3, end: 15 }
  * ```
  */
-export declare const calculateVisibleRange: ({ scrollTop, viewportHeight, itemHeight, totalItems, bufferSize, mode, totalContentHeight, heightCache }: VisibleRangeOptions) => SvelteVirtualListPreviousVisibleRange;
+export declare const calculateVisibleRange: ({ scrollTop, viewportHeight, itemHeight, totalItems, bufferSize, totalContentHeight, heightCache }: VisibleRangeOptions) => SvelteVirtualListPreviousVisibleRange;
 /**
  * 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 declare const calculateTransformY: (mode: SvelteVirtualListMode, totalItems: number, visibleEnd: number, visibleStart: number, itemHeight: number, viewportHeight: number, totalContentHeight?: number, heightCache?: Record<number, number>, measuredFallbackHeight?: number) => number;
+export declare const calculateTransformY: (totalItems: number, visibleStart: number, itemHeight: number, heightCache?: Record<number, number>) => number;
 /**
  * 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
@@ -147,7 +141,7 @@ export declare const updateHeightAndScroll: (state: VirtualListState, setters: V
 export declare const calculateAverageHeight: (itemElements: HTMLElement[], visibleRange: {
     start: number;
     end: number;
-}, heightCache: Record<number, number>, currentItemHeight: number, dirtyItems: Set<number>, currentTotalHeight?: number, currentValidCount?: number, mode?: SvelteVirtualListMode) => {
+}, heightCache: Record<number, number>, currentItemHeight: number, dirtyItems: Set<number>, currentTotalHeight?: number, currentValidCount?: number) => {
     newHeight: number;
     newLastMeasuredIndex: number;
     updatedHeightCache: Record<number, number>;