@humanspeak/svelte-virtual-list 0.2.6-beta.7 → 0.3.1-beta.0

package/dist/SvelteVirtualList.svelte

@@ -61,7 +61,7 @@
     MIT License © Humanspeak, Inc.
 -->
 
-<script lang="ts">
+<script lang="ts" generics="TItem = any">
     /**
      * SvelteVirtualList Implementation Journey
      *
@@ -182,7 +182,7 @@
         import.meta.env.DEV && import.meta.env.VITE_SVELTE_VIRTUAL_LIST_DEBUG === 'true'
     /**
      * Core configuration props with default values
-     * @type {SvelteVirtualListProps}
+     * @type {SvelteVirtualListProps<TItem>}
      */
     const {
         items = [], // Array of items to be rendered in the virtual list
@@ -197,7 +197,7 @@
         mode = 'topToBottom', // Scroll direction mode
         bufferSize = 20, // Number of items to render outside visible area
         testId // Base test ID for component elements (undefined = no data-testid attributes)
-    }: SvelteVirtualListProps = $props()
+    }: SvelteVirtualListProps<TItem> = $props()
 
     /**
      * DOM References and Core State

package/dist/SvelteVirtualList.svelte.d.ts

@@ -89,6 +89,141 @@
      * - Progressive size adjustment system
      */
 import { type SvelteVirtualListProps, type SvelteVirtualListScrollOptions } from './types.js';
+declare function $$render<TItem = any>(): {
+    props: SvelteVirtualListProps<TItem>;
+    exports: {
+        /**
+             * 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 {Promise<void>} Promise that resolves when scrolling is complete
+             * @throws {Error} If the index is out of bounds and shouldThrowOnBounds is true
+             */ scroll: (options: SvelteVirtualListScrollOptions) => Promise<void>;
+    };
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<TItem = any> {
+    props(): ReturnType<typeof $$render<TItem>>['props'];
+    events(): ReturnType<typeof $$render<TItem>>['events'];
+    slots(): ReturnType<typeof $$render<TItem>>['slots'];
+    bindings(): "";
+    exports(): {
+        /**
+             * 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 {Promise<void>} Promise that resolves when scrolling is complete
+             * @throws {Error} If the index is out of bounds and shouldThrowOnBounds is true
+             */ scroll: (options: SvelteVirtualListScrollOptions) => Promise<void>;
+    };
+}
+interface $$IsomorphicComponent {
+    new <TItem = any>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<TItem>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<TItem>['props']>, ReturnType<__sveltets_Render<TItem>['events']>, ReturnType<__sveltets_Render<TItem>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<TItem>['bindings']>;
+    } & ReturnType<__sveltets_Render<TItem>['exports']>;
+    <TItem = any>(internal: unknown, props: ReturnType<__sveltets_Render<TItem>['props']> & {}): ReturnType<__sveltets_Render<TItem>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
 /**
  * SvelteVirtualList
  *
@@ -151,63 +286,6 @@ import { type SvelteVirtualListProps, type SvelteVirtualListScrollOptions } from
  *
  * MIT License © Humanspeak, Inc.
  */
-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 {Promise<void>} Promise that resolves when scrolling is complete
-         * @throws {Error} If the index is out of bounds and shouldThrowOnBounds is true
-         */ scroll: (options: SvelteVirtualListScrollOptions) => Promise<void>;
-}, "">;
-type SvelteVirtualList = ReturnType<typeof SvelteVirtualList>;
+declare const SvelteVirtualList: $$IsomorphicComponent;
+type SvelteVirtualList<TItem = any> = InstanceType<typeof SvelteVirtualList<TItem>>;
 export default SvelteVirtualList;

package/dist/reactive-height-manager/test/TestComponent.svelte

@@ -0,0 +1,78 @@
+<script lang="ts">
+    import { untrack } from 'svelte'
+    import { ReactiveHeightManager } from '../ReactiveHeightManager.svelte.js'
+    import type { HeightChange, HeightManagerConfig } from '../types.js'
+
+    interface Props {
+        config: HeightManagerConfig
+        onReactiveUpdate?: (data: {
+            totalHeight: number
+            measuredCount: number
+            effectRuns: number
+        }) => void
+    }
+
+    let { config, onReactiveUpdate }: Props = $props()
+
+    // Create the manager
+    const manager = new ReactiveHeightManager(config)
+
+    // Derived reactive values (clean, no side effects)
+    let currentTotalHeight = $derived(manager.totalHeight)
+    let currentMeasuredCount = $derived(manager.measuredCount)
+
+    // Effect run counter (non-reactive - just for tracking)
+    let effectRunCount = 0
+
+    // Reactive counter for DOM display (separate from effect logic)
+    let displayEffectRuns = $state(0)
+
+    // Simple effect that just notifies - no state modification
+    $effect(() => {
+        // Read the current values (triggers when manager changes)
+        const totalHeight = manager.totalHeight
+        const measuredCount = manager.measuredCount
+
+        // Increment counters
+        effectRunCount++
+        displayEffectRuns = effectRunCount // Update reactive display
+
+        // Notify parent with fresh values each time
+        onReactiveUpdate?.({
+            totalHeight,
+            measuredCount,
+            effectRuns: effectRunCount
+        })
+    })
+
+    // Export methods for testing
+    export function processDirtyHeights(changes: HeightChange[]) {
+        manager.processDirtyHeights(changes)
+    }
+
+    export function updateItemLength(newLength: number) {
+        manager.updateItemLength(newLength)
+    }
+
+    export function setItemHeight(height: number) {
+        manager.itemHeight = height
+    }
+
+    export function getReactiveData() {
+        return {
+            totalHeight: currentTotalHeight,
+            measuredCount: currentMeasuredCount,
+            effectRuns: displayEffectRuns
+        }
+    }
+
+    export function getManager() {
+        return manager
+    }
+</script>
+
+<div data-testid="reactive-test-component">
+    <div data-testid="total-height">{currentTotalHeight}</div>
+    <div data-testid="measured-count">{currentMeasuredCount}</div>
+    <div data-testid="effect-runs">{displayEffectRuns}</div>
+</div>

package/dist/reactive-height-manager/test/TestComponent.svelte.d.ts

@@ -0,0 +1,23 @@
+import { ReactiveHeightManager } from '../ReactiveHeightManager.svelte.js';
+import type { HeightChange, HeightManagerConfig } from '../types.js';
+interface Props {
+    config: HeightManagerConfig;
+    onReactiveUpdate?: (data: {
+        totalHeight: number;
+        measuredCount: number;
+        effectRuns: number;
+    }) => void;
+}
+declare const TestComponent: import("svelte").Component<Props, {
+    processDirtyHeights: (changes: HeightChange[]) => void;
+    updateItemLength: (newLength: number) => void;
+    setItemHeight: (height: number) => void;
+    getReactiveData: () => {
+        totalHeight: number;
+        measuredCount: number;
+        effectRuns: number;
+    };
+    getManager: () => ReactiveHeightManager;
+}, "">;
+type TestComponent = ReturnType<typeof TestComponent>;
+export default TestComponent;

package/dist/reactive-height-manager/types.d.ts

@@ -8,8 +8,8 @@ export interface HeightChange {
     readonly index: number;
     /** The previous height (undefined if first measurement) */
     readonly oldHeight: number | undefined;
-    /** The new height measurement */
-    readonly newHeight: number;
+    /** The new height measurement (undefined represents removal/unset) */
+    readonly newHeight: number | undefined;
 }
 /**
  * Configuration options for ReactiveHeightManager

package/dist/types.d.ts

@@ -10,7 +10,7 @@ export type SvelteVirtualListMode = 'topToBottom' | 'bottomToTop';
  *
  * @typedef {Object} SvelteVirtualListProps
  */
-export type SvelteVirtualListProps = {
+export type SvelteVirtualListProps<TItem = any> = {
     /**
      * Number of items to render outside the visible viewport for smooth scrolling.
      * @default 20
@@ -41,7 +41,7 @@ export type SvelteVirtualListProps = {
     /**
      * The complete array of items to be virtualized.
      */
-    items: any[];
+    items: TItem[];
     /**
      * CSS class to apply to individual item containers.
      */
@@ -54,7 +54,7 @@ export type SvelteVirtualListProps = {
     /**
      * 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]>;
+    renderItem: Snippet<[item: TItem, index: number]>;
     /**
      * Base test ID for component elements to facilitate testing.
      */

package/dist/utils/scrollCalculation.js

@@ -110,28 +110,16 @@ const calculateBottomToTopScrollTarget = (params) => {
  */
 const calculateTopToBottomScrollTarget = (params) => {
     const { align, targetIndex, calculatedItemHeight, height, scrollTop, firstVisibleIndex, lastVisibleIndex, heightCache } = params;
-    console.log('[DEBUG] calculateTopToBottomScrollTarget:', {
-        align,
-        targetIndex,
-        calculatedItemHeight,
-        height,
-        scrollTop,
-        firstVisibleIndex,
-        lastVisibleIndex,
-        heightCacheKeys: Object.keys(heightCache).length
-    });
     if (align === 'auto') {
         // If item is above the viewport, align to top
         if (targetIndex < firstVisibleIndex) {
             const scrollTarget = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
-            console.log(`[DEBUG] Item ${targetIndex} above viewport (${firstVisibleIndex}), scrolling to top:`, scrollTarget);
             return scrollTarget;
         }
         // 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);
-            console.log(`[DEBUG] Item ${targetIndex} below viewport (${lastVisibleIndex}), scrolling to bottom:`, scrollTarget);
             return scrollTarget;
         }
         else {
@@ -140,12 +128,6 @@ const calculateTopToBottomScrollTarget = (params) => {
             const itemBottom = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex + 1);
             const distanceToTop = Math.abs(scrollTop - itemTop);
             const distanceToBottom = Math.abs(scrollTop + height - itemBottom);
-            console.log(`[DEBUG] Item ${targetIndex} visible, choosing nearest edge:`, {
-                itemTop,
-                itemBottom,
-                distanceToTop,
-                distanceToBottom
-            });
             if (distanceToTop < distanceToBottom) {
                 return itemTop;
             }
@@ -156,7 +138,6 @@ const calculateTopToBottomScrollTarget = (params) => {
     }
     else if (align === 'top') {
         const scrollTarget = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
-        console.log(`[DEBUG] Align to top for index ${targetIndex}:`, scrollTarget);
         return scrollTarget;
     }
     else if (align === 'bottom') {

package/dist/utils/virtualList.js

@@ -33,14 +33,6 @@ export const calculateScrollPosition = (totalItems, itemHeight, containerHeight)
  */
 export const calculateVisibleRange = (scrollTop, viewportHeight, itemHeight, totalItems, bufferSize, mode, atBottom, wasAtBottomBeforeHeightChange, lastVisibleRange, totalContentHeight) => {
     if (mode === 'bottomToTop') {
-        // if (wasAtBottomBeforeHeightChange && lastVisibleRange) {
-        //     // console.log('calculateVisibleRange:wasAtBottomBeforeHeightChange', {
-        //     //     lastVisibleRange,
-        //     //     atBottom,
-        //     //     wasAtBottomBeforeHeightChange
-        //     // })
-        //     return lastVisibleRange
-        // }
         const visibleCount = Math.ceil(viewportHeight / itemHeight) + 1;
         // In bottomToTop mode, scrollTop represents distance from the total content end
         // scrollTop = 0 means we're at the beginning (showing first items)
@@ -50,37 +42,16 @@ export const calculateVisibleRange = (scrollTop, viewportHeight, itemHeight, tot
         // Convert scrollTop to "distance from start" for bottomToTop
         const distanceFromStart = maxScrollTop - scrollTop;
         const startIndex = Math.floor(distanceFromStart / itemHeight);
-        // console.log(
-        //     `[DEBUG] calculateVisibleRange bottomToTop: scrollTop=${scrollTop}, maxScrollTop=${maxScrollTop}, distanceFromStart=${distanceFromStart}, startIndex=${startIndex}`
-        // )
         // Safeguard: handle edge cases
         if (startIndex < 0) {
             // We're scrolled beyond the maximum (showing first items)
             const start = 0;
             const end = Math.min(totalItems, visibleCount + bufferSize * 2);
-            // console.log(
-            //     `[DEBUG] calculateVisibleRange (startIndex < 0): start=${start}, end=${end}`
-            // )
-            // console.log('calculateVisibleRange:startIndex < 0', {
-            //     start,
-            //     end,
-            //     atBottom,
-            //     wasAtBottomBeforeHeightChange,
-            //     lastVisibleRange
-            // })
             return { start, end };
         }
         // Add buffer to both ends
         const start = Math.max(0, startIndex - bufferSize);
         const end = Math.min(totalItems, startIndex + visibleCount + bufferSize);
-        // console.log(`[DEBUG] calculateVisibleRange result: start=${start}, end=${end}`)
-        // console.log('calculateVisibleRange:startIndex >= 0', {
-        //     start,
-        //     end,
-        //     atBottom,
-        //     wasAtBottomBeforeHeightChange,
-        //     lastVisibleRange
-        // })
         return { start, end };
     }
     else {
@@ -102,13 +73,6 @@ export const calculateVisibleRange = (scrollTop, viewportHeight, itemHeight, tot
                 end: adjustedEnd
             };
         }
-        // console.log('calculateVisibleRange:isNotAtBottom', {
-        //     start: Math.max(0, start - bufferSize),
-        //     end: Math.min(totalItems, end + bufferSize),
-        //     atBottom,
-        //     wasAtBottomBeforeHeightChange,
-        //     lastVisibleRange
-        // })
         // Add buffer to both ends
         const finalStart = Math.max(0, start - bufferSize);
         const finalEnd = Math.min(totalItems, end + bufferSize);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@humanspeak/svelte-virtual-list",
-    "version": "0.2.6-beta.7",
+    "version": "0.3.1-beta.0",
     "description": "A lightweight, high-performance virtual list component for Svelte 5 that renders large datasets with minimal memory usage. Features include dynamic height support, smooth scrolling, TypeScript support, and efficient DOM recycling. Ideal for infinite scrolling lists, data tables, chat interfaces, and any application requiring the rendering of thousands of items without compromising performance. Zero dependencies and fully customizable.",
     "keywords": [
         "svelte",
@@ -44,8 +44,7 @@
         "dist",
         "!dist/**/*.test.*",
         "!dist/**/*.spec.*",
-        "!dist/test/**/*",
-        "!dist/reactive-height-manager/test/**/*"
+        "!dist/test/**/*"
     ],
     "scripts": {
         "build": "vite build && npm run package",
@@ -110,7 +109,7 @@
         "svelte-check": "^4.3.1",
         "typescript": "^5.9.2",
         "typescript-eslint": "^8.39.0",
-        "vite": "^7.1.0",
+        "vite": "^7.1.1",
         "vitest": "^3.2.4"
     },
     "peerDependencies": {