@humanspeak/svelte-virtual-list 0.5.2 → 0.5.4

package/README.md

@@ -232,6 +232,25 @@ pnpm test:all
 
 This project uses [Trunk](https://trunk.io) for formatting and linting. Trunk manages tool versions and runs checks automatically via pre-commit hooks.
 
+<!-- docs-kit:ecosystem start -->
+
+## Svelte 5 ecosystem
+
+Part of the [Humanspeak](https://humanspeak.com) family of runes-native Svelte 5 packages:
+
+| Package | Description |
+| --- | --- |
+| [@humanspeak/svelte-markdown](https://markdown.svelte.page) | Runtime markdown renderer for Svelte |
+| **[@humanspeak/svelte-virtual-list](https://virtuallist.svelte.page)** — _this package_ | Virtual scrolling for Svelte |
+| [@humanspeak/svelte-motion](https://motion.svelte.page) | Framer Motion for Svelte 5 |
+| [@humanspeak/svelte-headless-table](https://table.svelte.page) | Headless data tables for Svelte |
+| [@humanspeak/svelte-diff-match-patch](https://diff.svelte.page) | Diff comparison for Svelte |
+| [@humanspeak/svelte-purify](https://purify.svelte.page) | HTML sanitisation for Svelte |
+| [@humanspeak/svelte-virtual-chat](https://virtualchat.svelte.page) | Virtual chat viewport for Svelte 5 |
+| [@humanspeak/memory-cache](https://memory.svelte.page) | In-memory cache for TypeScript |
+| [@humanspeak/svelte-json-view-lite](https://jsonview.svelte.page) | JSON tree viewer for Svelte 5 |
+| [@humanspeak/svelte-scoped-props](https://scoped.svelte.page) | Scoped class props for Svelte |
+
 ## License
 
 MIT © [Humanspeak, Inc.](LICENSE)
@@ -239,3 +258,5 @@ MIT © [Humanspeak, Inc.](LICENSE)
 ## Credits
 
 Made with ❤️ by [Humanspeak](https://humanspeak.com)
+
+<!-- docs-kit:ecosystem end -->

package/dist/SvelteVirtualList.svelte

@@ -161,6 +161,7 @@
     } from './utils/virtualList.js'
     import { createDebugInfo, shouldShowDebugInfo } from './utils/virtualListDebug.js'
     import { calculateScrollTarget } from './utils/scrollCalculation.js'
+    import { waitForScrollEnd } from './utils/scrollEnd.js'
     import { createAdvancedThrottledCallback } from './utils/throttle.js'
     import { ReactiveListManager } from './index.js'
     import { BROWSER } from 'esm-env'
@@ -222,6 +223,7 @@
     let heightUpdateTimeout: ReturnType<typeof setTimeout> | null = null // Debounce timer for height updates
     let resizeObserver: ResizeObserver | null = null // Watches for container size changes
     let itemResizeObserver: ResizeObserver | null = null // Watches for individual item size changes
+    let scrollAbortController: AbortController | null = null // Cancels an in-flight programmatic scroll wait
 
     /**
      * Performance Optimization State
@@ -686,6 +688,8 @@
                 if (itemResizeObserver) {
                     itemResizeObserver.disconnect()
                 }
+                // Abort any pending scroll wait so its timers/listeners are torn down.
+                scrollAbortController?.abort()
             }
         }
     })
@@ -758,14 +762,14 @@
      *   {/snippet}
      * </SvelteVirtualList>
      *
-     * @returns {void}
+     * @returns {Promise<void>} Promise that resolves when scrolling is complete
      * @throws {Error} If the index is out of bounds and shouldThrowOnBounds is true
      */
     export const scrollToIndex = (
         index: number,
         smoothScroll = true,
         shouldThrowOnBounds = true
-    ): void => {
+    ): Promise<void> => {
         // Deprecation warning
         console.warn(
             'SvelteVirtualList: scrollToIndex is deprecated and will be removed in a future version. ' +
@@ -773,7 +777,7 @@
         )
 
         // Call the new scroll function with the provided parameters
-        scroll({ index, smoothScroll, shouldThrowOnBounds })
+        return scroll({ index, smoothScroll, shouldThrowOnBounds })
     }
 
     /**
@@ -801,90 +805,130 @@
      * @returns {Promise<void>} Promise that resolves when scrolling is complete
      * @throws {Error} If the index is out of bounds and shouldThrowOnBounds is true
      */
-    export const scroll = async (options: SvelteVirtualListScrollOptions): Promise<void> => {
+    export const scroll = (options: SvelteVirtualListScrollOptions): Promise<void> => {
         const { index, smoothScroll, shouldThrowOnBounds, align } = {
             ...DEFAULT_SCROLL_OPTIONS,
             ...options
         }
 
-        if (!items.length) return
-        if (!heightManager.viewportElement) {
-            tick().then(() => {
-                if (!heightManager.viewportElement) return
-                scroll({ index, smoothScroll, shouldThrowOnBounds, align })
-            })
-            return
-        }
-
-        // Bounds checking
-        let targetIndex = index
-        if (targetIndex < 0 || targetIndex >= items.length) {
-            if (shouldThrowOnBounds) {
-                throw new Error(
-                    `scroll: index ${targetIndex} is out of bounds (0-${items.length - 1})`
-                )
-            } else {
-                targetIndex = clampValue(targetIndex, 0, items.length - 1)
+        // Cancel any scroll wait still in progress so its promise can't resolve
+        // against a stale target, and start a fresh cancellation scope.
+        scrollAbortController?.abort()
+        const abortController = new AbortController()
+        scrollAbortController = abortController
+        const { signal } = abortController
+
+        return new Promise<void>((resolve, reject) => {
+            if (!items.length) {
+                resolve()
+                return
             }
-        }
 
-        const { start: firstVisibleIndex, end: lastVisibleIndex } = visibleItems
+            // Viewport not mounted yet: retry on the next tick and chain the result.
+            if (!heightManager.viewportElement) {
+                tick().then(() => {
+                    // A newer scroll() may have superseded this one while we waited;
+                    // bail out instead of re-invoking and clobbering the newer target.
+                    if (signal.aborted) {
+                        resolve()
+                        return
+                    }
+                    if (!heightManager.viewportElement) {
+                        resolve()
+                        return
+                    }
+                    scroll({ index, smoothScroll, shouldThrowOnBounds, align }).then(
+                        resolve,
+                        reject
+                    )
+                })
+                return
+            }
 
-        // Use extracted scroll calculation utility
-        const scrollTarget = calculateScrollTarget({
-            align: align || 'auto',
-            targetIndex,
-            itemsLength: items.length,
-            calculatedItemHeight: heightManager.averageHeight, // Use dynamic average from ReactiveListManager
-            height,
-            scrollTop: heightManager.scrollTop,
-            firstVisibleIndex,
-            lastVisibleIndex,
-            heightCache: heightManager.getHeightCache()
-        })
+            // Bounds checking
+            let targetIndex = index
+            if (targetIndex < 0 || targetIndex >= items.length) {
+                if (shouldThrowOnBounds) {
+                    reject(
+                        new Error(
+                            `scroll: index ${targetIndex} is out of bounds (0-${items.length - 1})`
+                        )
+                    )
+                    return
+                } else {
+                    targetIndex = clampValue(targetIndex, 0, items.length - 1)
+                }
+            }
 
-        // Handle early return for 'nearest' alignment when item is already visible
-        if (scrollTarget === null) {
-            return
-        }
+            const { start: firstVisibleIndex, end: lastVisibleIndex } = visibleItems
 
-        if (INTERNAL_DEBUG && heightManager.viewportElement) {
-            const domMax = Math.max(
-                0,
-                heightManager.viewport.scrollHeight - heightManager.viewport.clientHeight
-            )
-            console.info('[SVL] scroll-intent', {
-                targetIndex,
+            // Use extracted scroll calculation utility
+            const scrollTarget = calculateScrollTarget({
                 align: align || 'auto',
+                targetIndex,
+                itemsLength: items.length,
+                calculatedItemHeight: heightManager.averageHeight, // Use dynamic average from ReactiveListManager
+                height,
+                scrollTop: heightManager.scrollTop,
                 firstVisibleIndex,
                 lastVisibleIndex,
-                currentScrollTop: heightManager.scrollTop,
-                scrollTarget,
-                domMaxScrollTop: domMax
+                heightCache: heightManager.getHeightCache()
             })
-        }
 
-        heightManager.viewport.scrollTo({
-            top: scrollTarget,
-            behavior: smoothScroll ? 'smooth' : 'auto'
-        })
+            // Handle early return for 'nearest' alignment when item is already visible
+            if (scrollTarget === null) {
+                resolve()
+                return
+            }
 
-        // Update scrollTop state in next frame to avoid synchronous re-renders
-        requestAnimationFrame(() => {
-            heightManager.scrollTop = scrollTarget
             if (INTERNAL_DEBUG && heightManager.viewportElement) {
                 const domMax = Math.max(
                     0,
                     heightManager.viewport.scrollHeight - heightManager.viewport.clientHeight
                 )
-                console.info('[SVL] scroll-after-call', {
-                    scrollTop: heightManager.scrollTop,
+                console.info('[SVL] scroll-intent', {
+                    targetIndex,
+                    align: align || 'auto',
+                    firstVisibleIndex,
+                    lastVisibleIndex,
+                    currentScrollTop: heightManager.scrollTop,
+                    scrollTarget,
                     domMaxScrollTop: domMax
                 })
             }
-        })
 
-        // No extra alignment step here; allow native smooth scroll to reach DOM max scrollTop
+            heightManager.viewport.scrollTo({
+                top: scrollTarget,
+                behavior: smoothScroll ? 'smooth' : 'auto'
+            })
+
+            // Update scrollTop state in next frame to avoid synchronous re-renders
+            requestAnimationFrame(() => {
+                heightManager.scrollTop = scrollTarget
+                if (INTERNAL_DEBUG && heightManager.viewportElement) {
+                    const domMax = Math.max(
+                        0,
+                        heightManager.viewport.scrollHeight - heightManager.viewport.clientHeight
+                    )
+                    console.info('[SVL] scroll-after-call', {
+                        scrollTop: heightManager.scrollTop,
+                        domMaxScrollTop: domMax
+                    })
+                }
+            })
+
+            // Resolve only once the scroll has visually finished AND the virtual
+            // list has re-rendered for the new position.
+            waitForScrollEnd(
+                heightManager.viewport,
+                scrollTarget,
+                smoothScroll ?? true,
+                signal
+            ).then(async () => {
+                await tick()
+                resolve()
+            }, reject)
+        })
     }
 
     /**

package/dist/SvelteVirtualList.svelte.d.ts

@@ -114,9 +114,9 @@ declare function $$render<TItem = unknown>(): {
              *   {/snippet}
              * </SvelteVirtualList>
              *
-             * @returns {void}
+             * @returns {Promise<void>} Promise that resolves when scrolling is complete
              * @throws {Error} If the index is out of bounds and shouldThrowOnBounds is true
-             */ scrollToIndex: (index: number, smoothScroll?: boolean, shouldThrowOnBounds?: boolean) => void;
+             */ scrollToIndex: (index: number, smoothScroll?: boolean, shouldThrowOnBounds?: boolean) => Promise<void>;
         /**
              * Scrolls the virtual list to the item at the given index using a type-based options approach.
              *
@@ -181,9 +181,9 @@ declare class __sveltets_Render<TItem = unknown> {
              *   {/snippet}
              * </SvelteVirtualList>
              *
-             * @returns {void}
+             * @returns {Promise<void>} Promise that resolves when scrolling is complete
              * @throws {Error} If the index is out of bounds and shouldThrowOnBounds is true
-             */ scrollToIndex: (index: number, smoothScroll?: boolean, shouldThrowOnBounds?: boolean) => void;
+             */ scrollToIndex: (index: number, smoothScroll?: boolean, shouldThrowOnBounds?: boolean) => Promise<void>;
         /**
              * Scrolls the virtual list to the item at the given index using a type-based options approach.
              *

package/dist/utils/scrollEnd.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Utilities to detect when a programmatic scroll has visually finished.
+ *
+ * The browser's `scrollTo` returns immediately — it does not wait for a smooth
+ * animation to complete. These helpers bridge that gap so callers can await the
+ * real end of a scroll before reading layout or resolving a promise.
+ */
+/**
+ * Resolves once a programmatic scroll on `viewport` has visually finished.
+ *
+ * Resolution strategy:
+ * - Instant scroll (or already at target): resolves on the next animation frame,
+ *   once the browser has applied the new `scrollTop`.
+ * - Smooth scroll with native `scrollend` support: resolves on the `scrollend` event.
+ * - Smooth scroll without support (e.g. Safari): polls `scrollTop` until it
+ *   stabilizes for several consecutive frames or reaches the target.
+ *
+ * A safety timeout always resolves the promise to avoid hanging if neither the
+ * event nor the poll ever settles (e.g. an unreachable target or an interrupted
+ * animation). Passing an already-aborted (or later aborted) `signal` resolves
+ * immediately and tears down all listeners/timers.
+ *
+ * @example
+ * // Scroll smoothly and await the visual end, cancelling on a newer scroll:
+ * import { waitForScrollEnd } from './scrollEnd.js';
+ *
+ * const controller = new AbortController();
+ * const target = 1200;
+ * viewport.scrollTo({ top: target, behavior: 'smooth' });
+ * await waitForScrollEnd(viewport, target, true, controller.signal);
+ * // ...later, to abandon the wait (e.g. a newer scroll started):
+ * controller.abort();
+ *
+ * @param viewport The scrollable element being animated.
+ * @param target The desired final `scrollTop` value.
+ * @param smooth Whether the scroll was initiated with `behavior: 'smooth'`.
+ * @param signal Optional AbortSignal to cancel waiting (e.g. a newer scroll).
+ * @returns A promise that resolves when the scroll has finished (or is cancelled).
+ */
+export declare const waitForScrollEnd: (viewport: HTMLElement, target: number, smooth: boolean, signal?: AbortSignal) => Promise<void>;

package/dist/utils/scrollEnd.js

@@ -0,0 +1,114 @@
+/**
+ * Utilities to detect when a programmatic scroll has visually finished.
+ *
+ * The browser's `scrollTo` returns immediately — it does not wait for a smooth
+ * animation to complete. These helpers bridge that gap so callers can await the
+ * real end of a scroll before reading layout or resolving a promise.
+ */
+/** Hard safety timeout (ms): always resolve so a promise can never hang. */
+const SCROLL_END_TIMEOUT_MS = 1200;
+/** Number of consecutive stable frames required to consider a poll settled. */
+const STABLE_FRAMES = 3;
+/** Pixel tolerance when comparing scroll positions. */
+const POSITION_TOLERANCE = 1;
+/**
+ * Resolves once a programmatic scroll on `viewport` has visually finished.
+ *
+ * Resolution strategy:
+ * - Instant scroll (or already at target): resolves on the next animation frame,
+ *   once the browser has applied the new `scrollTop`.
+ * - Smooth scroll with native `scrollend` support: resolves on the `scrollend` event.
+ * - Smooth scroll without support (e.g. Safari): polls `scrollTop` until it
+ *   stabilizes for several consecutive frames or reaches the target.
+ *
+ * A safety timeout always resolves the promise to avoid hanging if neither the
+ * event nor the poll ever settles (e.g. an unreachable target or an interrupted
+ * animation). Passing an already-aborted (or later aborted) `signal` resolves
+ * immediately and tears down all listeners/timers.
+ *
+ * @example
+ * // Scroll smoothly and await the visual end, cancelling on a newer scroll:
+ * import { waitForScrollEnd } from './scrollEnd.js';
+ *
+ * const controller = new AbortController();
+ * const target = 1200;
+ * viewport.scrollTo({ top: target, behavior: 'smooth' });
+ * await waitForScrollEnd(viewport, target, true, controller.signal);
+ * // ...later, to abandon the wait (e.g. a newer scroll started):
+ * controller.abort();
+ *
+ * @param viewport The scrollable element being animated.
+ * @param target The desired final `scrollTop` value.
+ * @param smooth Whether the scroll was initiated with `behavior: 'smooth'`.
+ * @param signal Optional AbortSignal to cancel waiting (e.g. a newer scroll).
+ * @returns A promise that resolves when the scroll has finished (or is cancelled).
+ */
+export const waitForScrollEnd = (viewport, target, smooth, signal) => {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const alreadyThere = Math.abs(viewport.scrollTop - target) <= POSITION_TOLERANCE;
+        const shouldWaitForSmoothScroll = smooth && !alreadyThere;
+        let rafId = 0;
+        let onScrollEnd;
+        function cleanup() {
+            if (rafId)
+                cancelAnimationFrame(rafId);
+            if (timeoutId !== undefined)
+                clearTimeout(timeoutId);
+            if (onScrollEnd)
+                viewport.removeEventListener('scrollend', onScrollEnd);
+            signal?.removeEventListener('abort', onAbort);
+        }
+        function finish() {
+            cleanup();
+            resolve();
+        }
+        const onAbort = finish;
+        const timeoutId = shouldWaitForSmoothScroll
+            ? setTimeout(finish, SCROLL_END_TIMEOUT_MS)
+            : undefined;
+        // Instant scroll or no-op (already at target): a smooth `scrollTo` to the
+        // current position never fires `scrollend`, so handle it as instant.
+        if (!shouldWaitForSmoothScroll) {
+            rafId = requestAnimationFrame(() => {
+                rafId = 0;
+                finish();
+            });
+            return;
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+        // Smooth scroll with native `scrollend` support (Chrome, Firefox).
+        if (typeof window !== 'undefined' && 'onscrollend' in window) {
+            onScrollEnd = finish;
+            viewport.addEventListener('scrollend', onScrollEnd, { once: true });
+            return;
+        }
+        // Fallback (e.g. Safari): poll until `scrollTop` stabilizes or reaches target.
+        let lastTop = viewport.scrollTop;
+        let stableFrames = 0;
+        let hasMoved = false;
+        const poll = () => {
+            const top = viewport.scrollTop;
+            const delta = Math.abs(top - lastTop);
+            if (delta > POSITION_TOLERANCE) {
+                hasMoved = true;
+                stableFrames = 0;
+            }
+            else {
+                stableFrames += 1;
+            }
+            lastTop = top;
+            const nearTarget = Math.abs(top - target) <= POSITION_TOLERANCE;
+            if (nearTarget || (hasMoved && stableFrames >= STABLE_FRAMES)) {
+                rafId = 0;
+                finish();
+                return;
+            }
+            rafId = requestAnimationFrame(poll);
+        };
+        rafId = requestAnimationFrame(poll);
+    });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-virtual-list",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "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, activity feeds, and any application requiring the rendering of thousands of items without compromising performance. Zero dependencies and fully customizable.",
   "keywords": [
     "svelte",
@@ -65,39 +65,39 @@
     "@playwright/cli": "^0.1.13",
     "@playwright/test": "^1.60.0",
     "@sveltejs/adapter-auto": "^7.0.1",
-    "@sveltejs/kit": "^2.61.1",
-    "@sveltejs/package": "^2.5.7",
+    "@sveltejs/kit": "^2.64.0",
+    "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.1.2",
     "@tailwindcss/vite": "^4.3.0",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/svelte": "^5.3.1",
     "@testing-library/user-event": "^14.6.1",
-    "@types/node": "^25.9.1",
-    "@typescript-eslint/eslint-plugin": "^8.60.0",
-    "@typescript-eslint/parser": "^8.60.0",
-    "@vitest/coverage-v8": "^4.1.7",
-    "eslint": "^10.4.0",
+    "@types/node": "^25.9.2",
+    "@typescript-eslint/eslint-plugin": "^8.61.0",
+    "@typescript-eslint/parser": "^8.61.0",
+    "@vitest/coverage-v8": "^4.1.8",
+    "eslint": "^10.4.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-svelte": "^3.17.1",
+    "eslint-plugin-svelte": "^3.19.0",
     "eslint-plugin-unused-imports": "^4.4.1",
     "globals": "^17.6.0",
     "husky": "^9.1.7",
     "jsdom": "^29.1.1",
-    "mprocs": "^0.9.3",
-    "prettier": "^3.8.3",
+    "mprocs": "^0.9.6",
+    "prettier": "^3.8.4",
     "prettier-plugin-organize-imports": "^4.3.0",
-    "prettier-plugin-svelte": "^4.0.1",
+    "prettier-plugin-svelte": "^4.1.0",
     "prettier-plugin-tailwindcss": "^0.8.0",
     "publint": "^0.3.21",
-    "svelte": "^5.55.9",
-    "svelte-check": "^4.4.8",
+    "svelte": "^5.56.3",
+    "svelte-check": "^4.6.0",
     "tailwindcss": "^4.3.0",
     "tw-animate-css": "^1.4.0",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.60.0",
-    "vite": "^8.0.14",
-    "vitest": "^4.1.7"
+    "typescript-eslint": "^8.61.0",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.8"
   },
   "peerDependencies": {
     "svelte": "^5.0.0"