@humanspeak/svelte-virtual-list 0.4.0 → 0.4.1

package/README.md

@@ -31,108 +31,20 @@ A high-performance virtual list component for Svelte 5 applications that efficie
 - 🕹️ Programmatic scrolling with `scroll`
 - ♾️ Infinite scroll support with `onLoadMore`
 
-## scroll: Programmatic Scrolling
+## Requirements
 
-You can now programmatically scroll to any item in the list using the `scroll` method. This is useful for chat apps, jump-to-item navigation, and more. You can check the usage in `src/routes/tests/scroll`. Thank you for the feature request!
-
-### Usage Example
-
-```svelte
-<script lang="ts">
-    import SvelteVirtualList from '@humanspeak/svelte-virtual-list'
-    let listRef
-    const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, text: `Item ${i}` }))
-
-    function goToItem5000() {
-        // Scroll to item 5000 with smooth scrolling and auto alignment
-        listRef.scroll({ index: 5000, smoothScroll: true, align: 'auto' })
-    }
-</script>
-
-<button on:click={goToItem5000}> Scroll to item 5000 </button>
-<SvelteVirtualList {items} bind:this={listRef}>
-    {#snippet renderItem(item)}
-        <div>{item.text}</div>
-    {/snippet}
-</SvelteVirtualList>
-```
-
-### API
-
-- `scroll(options: { index: number; smoothScroll?: boolean; shouldThrowOnBounds?: boolean; align?: 'auto' | 'top' | 'bottom' | 'nearest' })`
-    - `index`: The item index to scroll to (0-based)
-    - `smoothScroll`: If true, uses smooth scrolling (default: true)
-    - `shouldThrowOnBounds`: If true, throws if index is out of bounds (default: true)
-    - `align`: Where to align the item in the viewport:
-        - `'auto'` (default): Only scroll if not visible, align to top or bottom as appropriate
-        - `'top'`: Always align to the top
-        - `'bottom'`: Always align to the bottom
-        - `'nearest'`: Scroll as little as possible to bring the item into view (like native scrollIntoView({ block: 'nearest' }))
-
-#### Usage Examples
-
-```svelte
-<button on:click={() => listRef.scroll({ index: 5000, align: 'nearest' })}>
-    Scroll to item 5000 (nearest)
-</button>
-```
-
-## Infinite Scroll
-
-Load more data automatically as users scroll near the end of the list. Perfect for paginated APIs, infinite feeds, and chat applications.
-
-```svelte
-<script lang="ts">
-    import SvelteVirtualList from '@humanspeak/svelte-virtual-list'
-
-    let items = $state([...initialItems])
-    let hasMore = $state(true)
-
-    async function loadMore() {
-        const newItems = await fetchMoreItems()
-        items = [...items, ...newItems]
-        if (newItems.length === 0) {
-            hasMore = false
-        }
-    }
-</script>
-
-<SvelteVirtualList {items} onLoadMore={loadMore} loadMoreThreshold={20} {hasMore}>
-    {#snippet renderItem(item)}
-        <div>{item.text}</div>
-    {/snippet}
-</SvelteVirtualList>
-```
-
-### Infinite Scroll Props
-
-| Prop                | Type                          | Default | Description                                          |
-| ------------------- | ----------------------------- | ------- | ---------------------------------------------------- |
-| `onLoadMore`        | `() => void \| Promise<void>` | -       | Callback when more data is needed (supports async)   |
-| `loadMoreThreshold` | `number`                      | `20`    | Number of items from the end to trigger `onLoadMore` |
-| `hasMore`           | `boolean`                     | `true`  | Set to `false` when all data has been loaded         |
-
-### Infinite Scroll Behavior
-
-- Triggers when scrolling near the end of the list
-- Automatically triggers on mount if initial items are below threshold
-- Prevents concurrent `onLoadMore` calls while loading
-- Works with both sync and async callbacks
-- Supports both `topToBottom` and `bottomToTop` modes
-
-### Integration Guides
-
-- [Infinite Scroll with Convex](documentation/CONVEX_INFINITE_SCROLL.md) - Real-time data + pagination with Convex backend
+- Svelte 5
+- Node.js 18+
 
 ## Installation
 
 ```bash
-# Using npm
-npm install @humanspeak/svelte-virtual-list
-
 # Using pnpm (recommended)
 pnpm add @humanspeak/svelte-virtual-list
 
+# Using npm
+npm install @humanspeak/svelte-virtual-list
+
 # Using yarn
 yarn add @humanspeak/svelte-virtual-list
 ```
@@ -156,9 +68,27 @@ yarn add @humanspeak/svelte-virtual-list
 </SvelteVirtualList>
 ```
 
-## Advanced Features
+## Props
 
-### Chat Application Example
+| Prop                         | Type                             | Default         | Description                                                                   |
+| ---------------------------- | -------------------------------- | --------------- | ----------------------------------------------------------------------------- |
+| `items`                      | `T[]`                            | Required        | Array of items to render                                                      |
+| `defaultEstimatedItemHeight` | `number`                         | `40`            | Initial height estimate used until items are measured                         |
+| `mode`                       | `'topToBottom' \| 'bottomToTop'` | `'topToBottom'` | Scroll direction and anchoring behavior                                       |
+| `bufferSize`                 | `number`                         | `20`            | Number of items rendered outside the viewport                                 |
+| `debug`                      | `boolean`                        | `false`         | Enable debug logging and visualizations                                       |
+| `containerClass`             | `string`                         | `''`            | Class for outer container                                                     |
+| `viewportClass`              | `string`                         | `''`            | Class for scrollable viewport                                                 |
+| `contentClass`               | `string`                         | `''`            | Class for content wrapper                                                     |
+| `itemsClass`                 | `string`                         | `''`            | Class for items container                                                     |
+| `testId`                     | `string`                         | `''`            | Base test id used in internal test hooks (useful for E2E/tests and debugging) |
+| `onLoadMore`                 | `() => void \| Promise<void>`    | -               | Callback when more data is needed for infinite scroll                         |
+| `loadMoreThreshold`          | `number`                         | `20`            | Items from end to trigger `onLoadMore`                                        |
+| `hasMore`                    | `boolean`                        | `true`          | Set to `false` when all data has been loaded                                  |
+
+## Bottom-to-Top Mode
+
+Use `mode="bottomToTop"` for chat-like lists anchored to the bottom:
 
 ```svelte
 <script lang="ts">
@@ -178,7 +108,7 @@ yarn add @humanspeak/svelte-virtual-list
 </script>
 
 <div style="height: 500px;">
-    <SvelteVirtualList items={messages} mode="bottomToTop" debug>
+    <SvelteVirtualList items={messages} mode="bottomToTop">
         {#snippet renderItem(message)}
             <div class="message-container">
                 <p>{message.text}</p>
@@ -191,40 +121,100 @@ yarn add @humanspeak/svelte-virtual-list
 </div>
 ```
 
-### Bottom-to-top mode
+## Programmatic Scrolling
 
-Use `mode="bottomToTop"` for chat-like lists anchored to the bottom. Programmatic scrolling uses the same API as top-to-bottom lists:
+Scroll to any item in the list using the `scroll` method. Useful for chat apps, jump-to-item navigation, and more.
 
 ```svelte
 <script lang="ts">
     import SvelteVirtualList from '@humanspeak/svelte-virtual-list'
     let listRef
-    const messages = Array.from({ length: 2000 }, (_, i) => ({ id: i, text: `Msg ${i}` }))
+    const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, text: `Item ${i}` }))
+
+    function goToItem5000() {
+        listRef.scroll({ index: 5000, smoothScroll: true, align: 'auto' })
+    }
 </script>
 
+<button onclick={goToItem5000}> Scroll to item 5000 </button>
+<SvelteVirtualList {items} bind:this={listRef}>
+    {#snippet renderItem(item)}
+        <div>{item.text}</div>
+    {/snippet}
+</SvelteVirtualList>
+```
+
+### scroll() Options
+
+| Option                | Type                                       | Default  | Description                             |
+| --------------------- | ------------------------------------------ | -------- | --------------------------------------- |
+| `index`               | `number`                                   | Required | The item index to scroll to (0-based)   |
+| `smoothScroll`        | `boolean`                                  | `true`   | Use smooth scrolling animation          |
+| `shouldThrowOnBounds` | `boolean`                                  | `true`   | Throw if index is out of bounds         |
+| `align`               | `'auto' \| 'top' \| 'bottom' \| 'nearest'` | `'auto'` | Where to align the item in the viewport |
+
+Alignment options:
+
+- `'auto'` - Only scroll if not visible, align to nearest edge
+- `'top'` - Always align to the top
+- `'bottom'` - Always align to the bottom
+- `'nearest'` - Scroll as little as possible to bring the item into view
+
+Works with both `topToBottom` and `bottomToTop` modes:
+
+```svelte
 <SvelteVirtualList items={messages} mode="bottomToTop" bind:this={listRef} />
-<button on:click={() => listRef.scroll({ index: messages.length - 1, align: 'bottom' })}>
+<button onclick={() => listRef.scroll({ index: messages.length - 1, align: 'bottom' })}>
     Jump to latest
 </button>
 ```
 
-## Props
+## Infinite Scroll
 
-| Prop                         | Type                             | Default         | Description                                                                   |
-| ---------------------------- | -------------------------------- | --------------- | ----------------------------------------------------------------------------- |
-| `items`                      | `T[]`                            | Required        | Array of items to render                                                      |
-| `defaultEstimatedItemHeight` | `number`                         | `40`            | Initial height estimate used until items are measured                         |
-| `mode`                       | `'topToBottom' \| 'bottomToTop'` | `'topToBottom'` | Scroll direction and anchoring behavior                                       |
-| `bufferSize`                 | `number`                         | `20`            | Number of items rendered outside the viewport                                 |
-| `debug`                      | `boolean`                        | `false`         | Enable debug logging and visualizations                                       |
-| `containerClass`             | `string`                         | `''`            | Class for outer container                                                     |
-| `viewportClass`              | `string`                         | `''`            | Class for scrollable viewport                                                 |
-| `contentClass`               | `string`                         | `''`            | Class for content wrapper                                                     |
-| `itemsClass`                 | `string`                         | `''`            | Class for items container                                                     |
-| `testId`                     | `string`                         | `''`            | Base test id used in internal test hooks (useful for E2E/tests and debugging) |
-| `onLoadMore`                 | `() => void \| Promise<void>`    | -               | Callback when more data is needed for infinite scroll                         |
-| `loadMoreThreshold`          | `number`                         | `20`            | Items from end to trigger `onLoadMore`                                        |
-| `hasMore`                    | `boolean`                        | `true`          | Set to `false` when all data has been loaded                                  |
+Load more data automatically as users scroll near the end of the list. Perfect for paginated APIs, infinite feeds, and chat applications.
+
+```svelte
+<script lang="ts">
+    import SvelteVirtualList from '@humanspeak/svelte-virtual-list'
+
+    let items = $state([...initialItems])
+    let hasMore = $state(true)
+
+    async function loadMore() {
+        const newItems = await fetchMoreItems()
+        items = [...items, ...newItems]
+        if (newItems.length === 0) {
+            hasMore = false
+        }
+    }
+</script>
+
+<SvelteVirtualList {items} onLoadMore={loadMore} loadMoreThreshold={20} {hasMore}>
+    {#snippet renderItem(item)}
+        <div>{item.text}</div>
+    {/snippet}
+</SvelteVirtualList>
+```
+
+### Infinite Scroll Behavior
+
+- Triggers when scrolling near the end of the list
+- Automatically triggers on mount if initial items are below threshold
+- Prevents concurrent `onLoadMore` calls while loading
+- Works with both sync and async callbacks
+- Supports both `topToBottom` and `bottomToTop` modes
+
+### Integration Guides
+
+- [Infinite Scroll with Convex](documentation/CONVEX_INFINITE_SCROLL.md) - Real-time data + pagination with Convex backend
+
+## Performance Considerations
+
+- The `bufferSize` prop affects memory usage and scroll smoothness
+- Items are measured and cached for optimal performance
+- Dynamic height calculations happen automatically
+- Resize observers handle container/content changes
+- Virtual DOM updates are batched for efficiency
 
 ## Testing
 
@@ -254,33 +244,6 @@ npx playwright test tests/docs-visit.spec.ts --project=chromium
 npx playwright test --debug
 ```
 
-### Development Commands
-
-```bash
-# Start development server
-pnpm dev
-
-# Start both package and docs
-pnpm run dev:all
-
-# Check TypeScript/Svelte
-pnpm run check
-
-# Build package
-pnpm run build
-
-# Format and lint code
-pnpm run lint:fix
-```
-
-## Performance Considerations
-
-- The `bufferSize` prop affects memory usage and scroll smoothness
-- Items are measured and cached for optimal performance
-- Dynamic height calculations happen automatically
-- Resize observers handle container/content changes
-- Virtual DOM updates are batched for efficiency
-
 ## Project Structure
 
 This is a **PNPM workspace** with two packages:
@@ -288,22 +251,34 @@ This is a **PNPM workspace** with two packages:
 1. **`./`** - Main Svelte Virtual List component package
 2. **`./docs`** - Documentation site with live demos and examples
 
-### Development Workflow
+### Development Commands
 
 ```bash
 # Install dependencies for both packages
 pnpm install
 
-# Run development servers simultaneously
+# Start development server
+pnpm dev
+
+# Start both package and docs
 pnpm run dev:all
 
-# Build both packages
+# Build package
 pnpm run build
 
-# Run tests across the workspace
+# Check TypeScript/Svelte
+pnpm run check
+
+# Format and lint code (uses Trunk)
+trunk fmt
+trunk check
+
+# Run all tests
 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.
+
 ## License
 
 MIT © [Humanspeak, Inc.](LICENSE)

package/dist/SvelteVirtualList.svelte

@@ -260,7 +260,7 @@
         const blockSums = buildBlockSums(cache, est, items.length)
         const offsetToIndex = getScrollOffsetForIndex(cache, est, anchorIndex, blockSums)
         const currentTop = heightManager.viewport.scrollTop
-        let offsetWithin = 0
+        let offsetWithin: number
         if (mode === 'bottomToTop') {
             // Convert distance-from-end to distance-from-start
             const distanceFromStart = maxScrollTop - currentTop
@@ -598,6 +598,7 @@
     // Keep height manager synchronized with items length
     $effect(() => {
         heightManager.updateItemLength(items.length)
+        stabilizedContentHeight = 0
     })
 
     // Infinite scroll: trigger onLoadMore when approaching end of list
@@ -1015,8 +1016,31 @@
      * Computed content height for the virtual list.
      * Uses the maximum of container height and total content height to ensure
      * proper scrolling behavior.
+     *
+     * In bottomToTop mode during active scroll, contentHeight is "ratcheted" —
+     * it can grow but never shrink. This prevents a feedback loop where
+     * averageHeight oscillation causes scrollHeight to bounce, triggering
+     * browser scrollTop adjustments that fire new scroll events.
+     * When scrolling stops (isScrolling goes false), it snaps to the true value.
      */
-    const contentHeight = $derived(Math.max(height, totalHeight))
+    let stabilizedContentHeight = 0
+
+    const contentHeight = $derived.by(() => {
+        const raw = Math.max(height, totalHeight)
+
+        if (mode !== 'bottomToTop' || !isScrolling) {
+            stabilizedContentHeight = raw
+            return raw
+        }
+
+        // During active scroll in bottomToTop: only allow growth (ratchet)
+        // Prevents shrink → scrollTop adjust → new scroll event feedback loop
+        if (raw > stabilizedContentHeight) {
+            stabilizedContentHeight = raw
+        }
+
+        return stabilizedContentHeight
+    })
 
     /**
      * Computed transform Y value for positioning the visible items.
@@ -1029,7 +1053,9 @@
         // Avoid synchronous DOM reads here; fall back once if height is 0
         const effectiveHeight = viewportHeight === 0 ? 400 : viewportHeight
 
-        // Use precise offset for topToBottom using measured heights when available
+        // Use precise offset using measured heights when available.
+        // For bottomToTop, pass ratcheted contentHeight so the transform stays
+        // stable while scrollHeight is stabilized (prevents visual shift).
         return Math.round(
             calculateTransformY(
                 mode,
@@ -1038,7 +1064,7 @@
                 visibleRange.start,
                 heightManager.averageHeight,
                 effectiveHeight,
-                totalHeight,
+                mode === 'bottomToTop' ? contentHeight : totalHeight,
                 heightManager.getHeightCache(),
                 measuredFallbackHeight
             )

package/dist/utils/virtualList.js

@@ -144,8 +144,17 @@ export const calculateTransformY = (mode, totalItems, visibleEnd, visibleStart,
     if (mode === 'bottomToTop') {
         // In bottomToTop mode, position items so they stack from bottom up
         const actualTotalHeight = totalContentHeight ?? totalItems * itemHeight;
-        // Calculate transform to position visible items correctly
-        const basicTransform = (totalItems - visibleEnd) * itemHeight;
+        // Calculate transform to position visible items correctly.
+        // Use measured heights when available to avoid oscillation caused by
+        // averageHeight changes shifting (totalItems - visibleEnd) * avg.
+        let basicTransform;
+        if (heightCache) {
+            const offsetToVisibleEnd = getScrollOffsetForIndex(heightCache, itemHeight, visibleEnd);
+            basicTransform = actualTotalHeight - offsetToVisibleEnd;
+        }
+        else {
+            basicTransform = (totalItems - visibleEnd) * itemHeight;
+        }
         // When content is smaller than viewport, push to bottom
         const bottomOffset = Math.max(0, effectiveViewport - actualTotalHeight);
         // Snap to integer pixels to avoid subpixel oscillation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-virtual-list",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "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",
@@ -91,7 +91,7 @@
     "prettier-plugin-svelte": "^3.4.1",
     "prettier-plugin-tailwindcss": "^0.7.2",
     "publint": "^0.3.17",
-    "svelte": "^5.51.2",
+    "svelte": "^5.51.3",
     "svelte-check": "^4.4.0",
     "tailwindcss": "^4.1.18",
     "tw-animate-css": "^1.4.0",