@humanspeak/svelte-virtual-list 0.2.4 → 0.2.6

package/dist/SvelteVirtualList.svelte.d.ts

@@ -1,46 +1,200 @@
-import type { SvelteVirtualListProps } from './types.js';
 /**
- * A high-performance virtualized list component that efficiently renders large datasets
- * by only mounting DOM nodes for visible items and a small buffer. Optimized for handling
- * lists of 10k+ items through chunked processing and progressive initialization.
+     * SvelteVirtualList Implementation Journey
+     *
+     * Evolution & Architecture:
+     * 1. Initial Implementation ✓
+     *    - Basic virtual scrolling with fixed height items
+     *    - Single direction scrolling (top-to-bottom)
+     *    - Simple viewport calculations
+     *
+     * 2. Dynamic Height Enhancement ✓
+     *    - Added dynamic height calculation system
+     *    - 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 ✓
+     *    - Added element recycling through keyed each blocks
+     *    - Implemented RAF for smooth animations
+     *    - Optimized DOM updates with transform translations
+     *
+     * 5. Stability Improvements ✓
+     *    - Added ResizeObserver for responsive updates
+     *    - Implemented proper cleanup on component destruction
+     *    - Added debug mode for development assistance
+     *
+     * 6. 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 ✓
+     *    - 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 ✓
+     *    - Extracted debug utilities for better testing
+     *    - Improved type safety throughout
+     *    - Added comprehensive documentation
+     *    - Optimized debug output to reduce noise
+     *
+     * 9. Future Improvements (Planned)
+     *    - Add horizontal scrolling support
+     *    - Implement variable-sized item caching
+     *    - Add keyboard navigation support
+     *    - Support for dynamic item updates
+     *    - 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
+     * - Browser compatibility issues
+     * - Performance optimization for 10k+ items
+     * - Progressive initialization for large datasets
+     * - Debug output optimization
+     * - Accurate size calculations with caching
+     * - Responsive size adjustments
+     *
+     * Current Architecture:
+     * - Four-layer DOM structure for optimal performance
+     * - State management using Svelte 5's $state
+     * - Reactive height and scroll calculations
+     * - Configurable buffer zones for smooth scrolling
+     * - Chunked processing system for large datasets
+     * - Separated debug utilities for better testing
+     * - Height caching and estimation system
+     * - Progressive size adjustment system
+     */
+import { type SvelteVirtualListProps, type SvelteVirtualListScrollOptions } from './types.js';
+/**
+ * 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.
  *
- * Props:
- * - `items` - Array of items to render
- * - `defaultEstimatedItemHeight` - Initial height estimate for items (default: 40px)
- * - `mode` - Scroll direction: 'topToBottom' or 'bottomToTop' (default: 'topToBottom')
- * - `debug` - Enable debug logging (default: false)
- * - `bufferSize` - Number of items to render outside visible area (default: 20)
- * - `containerClass` - Custom class for container element
- * - `viewportClass` - Custom class for viewport element
- * - `contentClass` - Custom class for content wrapper
- * - `itemsClass` - Custom class for items wrapper
- * - `debugFunction` - Custom debug logging function
- * - `testId` - Base test ID for component elements
+ * =============================
+ * ==  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
+ * - TypeScript and Svelte 5 runes/snippets support
+ * - Customizable styling via class props
+ * - Debug mode for development and testing
+ * - Optimized for large lists (10k+ items)
+ * - Comprehensive test coverage (unit and E2E)
  *
- * Usage:
+ * =============================
+ * ==  Usage Example          ==
+ * =============================
  * ```svelte
  * <SvelteVirtualList
  *     items={data}
- *     defaultEstimatedItemHeight={40}
- *     mode="topToBottom"
+ *     mode="bottomToTop"
+ *     bind:this={listRef}
  * >
- *     {#snippet renderItem(item, index)}
- *         <div class="item">{item.text}</div>
+ *     {#snippet renderItem(item)}
+ *         <div>{item.text}</div>
  *     {/snippet}
  * </SvelteVirtualList>
  * ```
  *
- * Features:
- * - Dynamic height calculation
- * - Bidirectional scrolling
- * - Configurable buffer size
- * - Debug mode
- * - Custom styling
- * - Progressive initialization for large datasets
- * - Memory-optimized for 10k+ items
- * - Chunked processing for smooth performance
- * - Progress tracking during initialization
+ * =============================
+ * ==  Architecture Notes      ==
+ * =============================
+ * - Uses a four-layer DOM structure for optimal performance
+ * - Only visible items + buffer are mounted in the DOM
+ * - Height caching and estimation for dynamic content
+ * - Handles resize events and dynamic content changes
+ * - Supports chunked initialization for very large lists
+ * - All scrolling logic is centralized in the scroll() method
+ * - Bi-directional support: mode="topToBottom" or "bottomToTop"
+ * - Designed for extensibility and easy debugging
+ *
+ * =============================
+ * ==  For Contributors        ==
+ * =============================
+ * - Please keep all scrolling logic in the scroll() method
+ * - Add new features behind feature flags or as optional props
+ * - Write tests for all new features (see /test and /tests/scroll)
+ * - Use TypeScript and Svelte 5 runes for all new code
+ * - Document all exported functions and props with JSDoc
+ * - See README.md for API and usage details
+ * - For questions, open an issue or discussion on GitHub
+ *
+ * MIT License © Humanspeak, Inc.
  */
-declare const SvelteVirtualList: import("svelte").Component<SvelteVirtualListProps, {}, "">;
+declare const SvelteVirtualList: import("svelte").Component<SvelteVirtualListProps, {
+    /**
+         * Scrolls the virtual list to the item at the given index.
+         *
+         * @deprecated This function is deprecated and will be removed in a future version.
+         * Use the new scroll method from the component instance instead.
+         *
+         * @function scrollToIndex
+         * @param index The index of the item to scroll to.
+         * @param smoothScroll (default: true) Whether to use smooth scrolling.
+         * @param shouldThrowOnBounds (default: true) Whether to throw an error if the index is out of bounds.
+         *
+         * @example
+         * // Svelte usage:
+         * // In your <script> block:
+         * import SvelteVirtualList from '@humanspeak/svelte-virtual-list';
+         * let virtualList;
+         * const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, text: `Item ${i}` }));
+         *
+         * // In your markup:
+         * <button onclick={() => virtualList.scrollToIndex(5000)}>
+         *    Scroll to 5000
+         * </button>
+         * <SvelteVirtualList {items} bind:this={virtualList}>
+         *   {#snippet renderItem(item)}
+         *     <div>{item.text}</div>
+         *   {/snippet}
+         * </SvelteVirtualList>
+         *
+         * @returns {void}
+         * @throws {Error} If the index is out of bounds and shouldThrowOnBounds is true
+         */ scrollToIndex: (index: number, smoothScroll?: boolean, shouldThrowOnBounds?: boolean) => void;
+    /**
+         * Scrolls the virtual list to the item at the given index using a type-based options approach.
+         *
+         * @function scroll
+         * @param options Configuration options for scrolling behavior.
+         *
+         * @example
+         * // Svelte usage:
+         * // In your <script> block:
+         *   import SvelteVirtualList from './index.js';
+         *   let virtualList;
+         *   const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, text: `Item ${i}` }));
+         *
+         * <button onclick={() => virtualList.scroll({ index: 5000 })}>
+         *   Scroll to 5000
+         * </button>
+         * <SvelteVirtualList {items} bind:this={virtualList}>
+         *   {#snippet renderItem(item)}
+         *     <div>{item.text}</div>
+         *   {/snippet}
+         * </SvelteVirtualList>
+         *
+         * @returns {void}
+         * @throws {Error} If the index is out of bounds and shouldThrowOnBounds is true
+         */ scroll: (options: SvelteVirtualListScrollOptions) => void;
+}, "">;
 type SvelteVirtualList = ReturnType<typeof SvelteVirtualList>;
 export default SvelteVirtualList;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 import SvelteVirtualList from './SvelteVirtualList.svelte';
-import type { SvelteVirtualListDebugInfo, SvelteVirtualListMode, SvelteVirtualListProps } from './types.js';
+import type { SvelteVirtualListDebugInfo, SvelteVirtualListMode, SvelteVirtualListProps, SvelteVirtualListScrollAlign, SvelteVirtualListScrollOptions } from './types.js';
 export default SvelteVirtualList;
-export type { SvelteVirtualListDebugInfo, SvelteVirtualListMode, SvelteVirtualListProps };
+export type { SvelteVirtualListDebugInfo, SvelteVirtualListMode, SvelteVirtualListProps, SvelteVirtualListScrollAlign, SvelteVirtualListScrollOptions };

package/dist/types.d.ts

@@ -9,35 +9,59 @@ export type SvelteVirtualListMode = 'topToBottom' | 'bottomToTop';
  * Configuration properties for the SvelteVirtualList component.
  *
  * @typedef {Object} SvelteVirtualListProps
- * @property {number} [bufferSize] - Number of items to render outside the visible viewport
- *     for smooth scrolling.
- * @property {string} [containerClass] - CSS class to apply to the outer container element.
- * @property {string} [contentClass] - CSS class to apply to the content wrapper element.
- * @property {number} [defaultEstimatedItemHeight] - Initial height estimate for each item in pixels.
- *     Used for optimization before actual measurements are available.
- * @property {boolean} [debug] - When true, enables debug mode with additional logging and information.
- * @property {Function} [debugFunction] - Custom callback to handle debug information.
- *     Receives a {@link SvelteVirtualListDebugInfo} object.
- * @property {Array<any>} items - The complete array of items to be virtualized.
- * @property {string} [itemsClass] - CSS class to apply to individual item containers.
- * @property {SvelteVirtualListMode} [mode='topToBottom'] - Determines the scroll and render direction.
- * @property {Snippet<[item: any, index: number]>} renderItem - Svelte snippet function that defines
- *     how each item should be rendered. Receives the item and its index as arguments.
- * @property {string} [testId] - Base test ID for component elements to facilitate testing.
- * @property {string} [viewportClass] - CSS class to apply to the scrollable viewport element.
  */
 export type SvelteVirtualListProps = {
+    /**
+     * Number of items to render outside the visible viewport for smooth scrolling.
+     * @default 20
+     */
     bufferSize?: number;
+    /**
+     * CSS class to apply to the outer container element.
+     */
     containerClass?: string;
+    /**
+     * CSS class to apply to the content wrapper element.
+     */
     contentClass?: string;
+    /**
+     * Initial height estimate for each item in pixels. Used for optimization before actual measurements are available.
+     * @default 40
+     */
     defaultEstimatedItemHeight?: number;
+    /**
+     * When true, enables debug mode with additional logging and information.
+     * @default false
+     */
     debug?: boolean;
+    /**
+     * Custom callback to handle debug information. Receives a SvelteVirtualListDebugInfo object.
+     */
     debugFunction?: (_info: SvelteVirtualListDebugInfo) => void;
+    /**
+     * The complete array of items to be virtualized.
+     */
     items: 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.
+     */
     renderItem: Snippet<[item: any, index: number]>;
+    /**
+     * Base test ID for component elements to facilitate testing.
+     */
     testId?: string;
+    /**
+     * CSS class to apply to the scrollable viewport element.
+     */
     viewportClass?: string;
 };
 /**
@@ -58,3 +82,21 @@ export type SvelteVirtualListDebugInfo = {
     processedItems: number;
     averageItemHeight: number;
 };
+export type SvelteVirtualListScrollAlign = 'auto' | 'top' | 'bottom';
+/**
+ * Options for scrolling to a specific index in the virtual list.
+ */
+export interface SvelteVirtualListScrollOptions {
+    /** The index of the item to scroll to. */
+    index: number;
+    /** Whether to use smooth scrolling animation. Default: true */
+    smoothScroll?: boolean;
+    /** Whether to throw an error if the index is out of bounds. Default: true */
+    shouldThrowOnBounds?: boolean;
+    /** Alignment for the scrolled item: 'auto', 'top', or 'bottom'. Default: 'auto' */
+    align?: SvelteVirtualListScrollAlign;
+}
+/**
+ * Default options for scrolling.
+ */
+export declare const DEFAULT_SCROLL_OPTIONS: Partial<SvelteVirtualListScrollOptions>;

package/dist/types.js

@@ -1 +1,8 @@
-export {};
+/**
+ * Default options for scrolling.
+ */
+export const DEFAULT_SCROLL_OPTIONS = {
+    smoothScroll: true,
+    shouldThrowOnBounds: true,
+    align: 'auto'
+};

package/dist/utils/heightCalculation.d.ts

@@ -0,0 +1,77 @@
+import type { HeightCache } from './types.js';
+/**
+ * Calculates and updates the average height of visible items with debouncing.
+ *
+ * This function optimizes performance by:
+ * - Debouncing calculations to prevent excessive DOM reads (200ms default)
+ * - Caching item heights to minimize recalculations
+ * - Only updating when significant changes are detected (>1px difference)
+ * - Early returns to prevent unnecessary processing
+ *
+ * Implementation details:
+ * - Uses a debounce timeout to batch height calculations
+ * - Tracks calculation state to prevent concurrent updates
+ * - Caches heights in heightCache for reuse
+ * - Validates browser environment and calculation state
+ * - Checks for meaningful height changes before updates
+ *
+ * State interactions:
+ * - Updates calculatedItemHeight when significant changes occur
+ * - Updates lastMeasuredIndex to track progress
+ * - Modifies heightCache to store measured heights
+ * - Uses isCalculatingHeight flag for concurrency control
+ *
+ * Guard clauses:
+ * - Returns null if not in browser environment
+ * - Returns null if calculation is already in progress
+ * - Returns null if update timeout is pending
+ * - Returns null if current index matches last measured
+ *
+ * @example
+ * ```typescript
+ * // Automatically called when items are rendered
+ * $effect(() => {
+ *     if (BROWSER && itemElements.length > 0 && !isCalculatingHeight) {
+ *         calculateAverageHeightDebounced(
+ *             false,
+ *             null,
+ *             () => getVisibleRange(),
+ *             itemElements,
+ *             heightCache,
+ *             lastMeasuredIndex,
+ *             currentHeight,
+ *             handleUpdate
+ *         )
+ *     }
+ * })
+ * ```
+ *
+ * Change History:
+ *
+ * 2025-01-22
+ * - Added comprehensive test coverage for all guard clauses
+ * - Improved browser environment detection
+ * - Enhanced debounce timing precision
+ * - Added proper cleanup for timeouts
+ * - Documented all edge cases and failure modes
+ *
+ *
+ * @param isCalculatingHeight - Flag to prevent concurrent calculations
+ * @param heightUpdateTimeout - Reference to existing update timeout
+ * @param visibleItemsGetter - Function to get current visible range
+ * @param itemElements - Array of DOM elements to measure
+ * @param heightCache - Cache of previously measured heights
+ * @param lastMeasuredIndex - Index of last measured element
+ * @param calculatedItemHeight - Current average height
+ * @param onUpdate - Callback for height updates
+ * @param debounceTime - Time to wait between calculations (default: 200ms)
+ * @returns Timeout object or null if calculation was skipped
+ */
+export declare const calculateAverageHeightDebounced: (isCalculatingHeight: boolean, heightUpdateTimeout: ReturnType<typeof setTimeout> | null, visibleItemsGetter: () => {
+    start: number;
+    end: number;
+}, itemElements: HTMLElement[], heightCache: HeightCache, lastMeasuredIndex: number, calculatedItemHeight: number, onUpdate: (result: {
+    newHeight: number;
+    newLastMeasuredIndex: number;
+    updatedHeightCache: HeightCache;
+}) => void, debounceTime?: number) => NodeJS.Timeout | null;

package/dist/utils/heightCalculation.js

@@ -0,0 +1,90 @@
+import { BROWSER } from 'esm-env';
+import { calculateAverageHeight } from './virtualList.js';
+/**
+ * Calculates and updates the average height of visible items with debouncing.
+ *
+ * This function optimizes performance by:
+ * - Debouncing calculations to prevent excessive DOM reads (200ms default)
+ * - Caching item heights to minimize recalculations
+ * - Only updating when significant changes are detected (>1px difference)
+ * - Early returns to prevent unnecessary processing
+ *
+ * Implementation details:
+ * - Uses a debounce timeout to batch height calculations
+ * - Tracks calculation state to prevent concurrent updates
+ * - Caches heights in heightCache for reuse
+ * - Validates browser environment and calculation state
+ * - Checks for meaningful height changes before updates
+ *
+ * State interactions:
+ * - Updates calculatedItemHeight when significant changes occur
+ * - Updates lastMeasuredIndex to track progress
+ * - Modifies heightCache to store measured heights
+ * - Uses isCalculatingHeight flag for concurrency control
+ *
+ * Guard clauses:
+ * - Returns null if not in browser environment
+ * - Returns null if calculation is already in progress
+ * - Returns null if update timeout is pending
+ * - Returns null if current index matches last measured
+ *
+ * @example
+ * ```typescript
+ * // Automatically called when items are rendered
+ * $effect(() => {
+ *     if (BROWSER && itemElements.length > 0 && !isCalculatingHeight) {
+ *         calculateAverageHeightDebounced(
+ *             false,
+ *             null,
+ *             () => getVisibleRange(),
+ *             itemElements,
+ *             heightCache,
+ *             lastMeasuredIndex,
+ *             currentHeight,
+ *             handleUpdate
+ *         )
+ *     }
+ * })
+ * ```
+ *
+ * Change History:
+ *
+ * 2025-01-22
+ * - Added comprehensive test coverage for all guard clauses
+ * - Improved browser environment detection
+ * - Enhanced debounce timing precision
+ * - Added proper cleanup for timeouts
+ * - Documented all edge cases and failure modes
+ *
+ *
+ * @param isCalculatingHeight - Flag to prevent concurrent calculations
+ * @param heightUpdateTimeout - Reference to existing update timeout
+ * @param visibleItemsGetter - Function to get current visible range
+ * @param itemElements - Array of DOM elements to measure
+ * @param heightCache - Cache of previously measured heights
+ * @param lastMeasuredIndex - Index of last measured element
+ * @param calculatedItemHeight - Current average height
+ * @param onUpdate - Callback for height updates
+ * @param debounceTime - Time to wait between calculations (default: 200ms)
+ * @returns Timeout object or null if calculation was skipped
+ */
+export const calculateAverageHeightDebounced = (isCalculatingHeight, heightUpdateTimeout, visibleItemsGetter, itemElements, heightCache, lastMeasuredIndex, calculatedItemHeight, 
+/* trunk-ignore(eslint/no-unused-vars) */
+onUpdate, debounceTime = 200) => {
+    if (!BROWSER || isCalculatingHeight || heightUpdateTimeout)
+        return null;
+    const visibleRange = visibleItemsGetter();
+    const currentIndex = visibleRange.start;
+    if (currentIndex === lastMeasuredIndex)
+        return null;
+    return setTimeout(() => {
+        const { newHeight, newLastMeasuredIndex, updatedHeightCache } = calculateAverageHeight(itemElements, visibleRange, heightCache, calculatedItemHeight);
+        if (Math.abs(newHeight - calculatedItemHeight) > 1) {
+            onUpdate({
+                newHeight,
+                newLastMeasuredIndex,
+                updatedHeightCache
+            });
+        }
+    }, debounceTime);
+};

package/dist/utils/raf.d.ts

@@ -1,8 +1,32 @@
 /**
- * Schedules a function to be executed on the next animation frame.
- * If a function is already scheduled, the new function will replace it.
- * This helps prevent multiple RAF calls and ensures smooth animations.
+ * Creates a requestAnimationFrame (RAF) scheduler for debouncing animation frame callbacks.
  *
- * @param fn - The function to be executed on the next animation frame
+ * This factory returns a function that schedules a callback to run on the next animation frame.
+ * If multiple calls are made before the frame executes, only the last callback is executed.
+ *
+ * This is ideal for scenarios where you want to batch or debounce UI updates, such as scroll or resize handlers,
+ * without risking global state leaks or cross-component interference.
+ *
+ * ### Why use this?
+ * - Prevents redundant RAF calls and excessive re-renders.
+ * - Ensures only the latest callback is executed per frame.
+ * - Each scheduler instance is independent—no global state is shared.
+ *
+ * @example
+ * // Svelte usage example:
+ * <script lang="ts">
+ *   import { createRafScheduler } from './raf.js';
+ *   const rafSchedule = createRafScheduler();
+ *   function onScroll() {
+ *     rafSchedule(() => {
+ *       // Perform expensive DOM measurement or update
+ *     });
+ *   }
+ * </script>
+ * <div on:scroll={onScroll}> ... </div>
+ *
+ * @returns {(fn: () => void) => void} A scheduler function. Call with a callback to schedule it for the next animation frame.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame
  */
-export declare const rafSchedule: (fn: () => void) => void;
+export declare function createRafScheduler(): (fn: () => void) => void;

package/dist/utils/raf.js

@@ -1,22 +1,48 @@
-let scheduled = false;
-let callback = null;
 /**
- * Schedules a function to be executed on the next animation frame.
- * If a function is already scheduled, the new function will replace it.
- * This helps prevent multiple RAF calls and ensures smooth animations.
+ * Creates a requestAnimationFrame (RAF) scheduler for debouncing animation frame callbacks.
  *
- * @param fn - The function to be executed on the next animation frame
+ * This factory returns a function that schedules a callback to run on the next animation frame.
+ * If multiple calls are made before the frame executes, only the last callback is executed.
+ *
+ * This is ideal for scenarios where you want to batch or debounce UI updates, such as scroll or resize handlers,
+ * without risking global state leaks or cross-component interference.
+ *
+ * ### Why use this?
+ * - Prevents redundant RAF calls and excessive re-renders.
+ * - Ensures only the latest callback is executed per frame.
+ * - Each scheduler instance is independent—no global state is shared.
+ *
+ * @example
+ * // Svelte usage example:
+ * <script lang="ts">
+ *   import { createRafScheduler } from './raf.js';
+ *   const rafSchedule = createRafScheduler();
+ *   function onScroll() {
+ *     rafSchedule(() => {
+ *       // Perform expensive DOM measurement or update
+ *     });
+ *   }
+ * </script>
+ * <div on:scroll={onScroll}> ... </div>
+ *
+ * @returns {(fn: () => void) => void} A scheduler function. Call with a callback to schedule it for the next animation frame.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame
  */
-export const rafSchedule = (fn) => {
-    callback = fn;
-    if (!scheduled) {
-        scheduled = true;
-        requestAnimationFrame(() => {
-            scheduled = false;
-            if (callback) {
-                callback();
-                callback = null;
-            }
-        });
-    }
-};
+export function createRafScheduler() {
+    let scheduled = false;
+    let callback = null;
+    return (fn) => {
+        callback = fn;
+        if (!scheduled) {
+            scheduled = true;
+            requestAnimationFrame(() => {
+                scheduled = false;
+                if (callback) {
+                    callback();
+                    callback = null;
+                }
+            });
+        }
+    };
+}

package/dist/utils/types.d.ts

@@ -39,3 +39,9 @@ export type VirtualListSetters = {
     setScrollTop: (scrollTop: number) => void;
     setInitialized: (initialized: boolean) => void;
 };
+/**
+ * Cache for storing measured item heights
+ * - Key: Item index in the list
+ * - Value: Measured height in pixels
+ */
+export type HeightCache = Record<number, number>;