@humanspeak/svelte-headless-table 6.0.3 → 6.0.5

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2024-2025 Humanspeak, Inc.
+Copyright (c) 2024-2026 Humanspeak, Inc.
 
 Copyright (c) 2022-2024 Bryan Lee
 

package/README.md

@@ -60,6 +60,7 @@ Easily extend Svelte Headless Table with complex **sorting**, **filtering**, **g
 - [x] [addSelectedRows](https://table.svelte.page/docs/plugins/add-selected-rows)
 - [x] [addResizedColumns](https://table.svelte.page/docs/plugins/add-resized-columns)
 - [x] [addGridLayout](https://table.svelte.page/docs/plugins/add-grid-layout)
+- [x] [addVirtualScroll](https://table.svelte.page/docs/plugins/add-virtual-scroll)
 
 ## Examples
 

package/dist/bodyRows.js

@@ -242,17 +242,12 @@ export const getColumnedBodyRows = (rows, columnIdOrder) => {
             clonedCell.row = columnedRows[rowIdx];
             return clonedCell;
         });
-        const visibleCells = columnIdOrder
-            .map((cid) => {
-            return cells.find((c) => c.id === cid);
-        })
-            .filter(nonUndefined);
+        const cellById = new Map(cells.map((c) => [c.id, c]));
+        const visibleCells = columnIdOrder.map((cid) => cellById.get(cid)).filter(nonUndefined);
         columnedRows[rowIdx].cells = visibleCells;
         // Include hidden cells in `cellForId` to allow row transformations on
         // hidden cells.
-        cells.forEach((cell) => {
-            columnedRows[rowIdx].cellForId[cell.id] = cell;
-        });
+        columnedRows[rowIdx].cellForId = Object.fromEntries(cellById);
     });
     return columnedRows;
 };

package/dist/createViewModel.js

@@ -162,27 +162,22 @@ export const createViewModel = (table, columns, { rowDataId } = {}) => {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         rows = fn(rows);
     });
+    const pluginEntries = Object.entries(pluginInstances);
     const injectedRows = derived(rows, ($rows) => {
         derivationCalls.injectedRows++;
-        // Inject state.
         $rows.forEach((row) => {
             row.injectState(tableState);
-            row.cells.forEach((cell) => {
-                cell.injectState(tableState);
-            });
-        });
-        // Apply plugin component hooks.
-        Object.entries(pluginInstances).forEach(([pluginName, pluginInstance]) => {
-            $rows.forEach((row) => {
-                if (pluginInstance.hooks?.['tbody.tr'] !== undefined) {
-                    row.applyHook(pluginName, pluginInstance.hooks['tbody.tr'](row));
+            row.cells.forEach((cell) => cell.injectState(tableState));
+            for (const [pluginName, pluginInstance] of pluginEntries) {
+                const trHook = pluginInstance.hooks?.['tbody.tr'];
+                if (trHook !== undefined) {
+                    row.applyHook(pluginName, trHook(row));
                 }
-                row.cells.forEach((cell) => {
-                    if (pluginInstance.hooks?.['tbody.tr.td'] !== undefined) {
-                        cell.applyHook(pluginName, pluginInstance.hooks['tbody.tr.td'](cell));
-                    }
-                });
-            });
+                const tdHook = pluginInstance.hooks?.['tbody.tr.td'];
+                if (tdHook !== undefined) {
+                    row.cells.forEach((cell) => cell.applyHook(pluginName, tdHook(cell)));
+                }
+            }
         });
         _rows.set($rows);
         return $rows;
@@ -196,53 +191,29 @@ export const createViewModel = (table, columns, { rowDataId } = {}) => {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         pageRows = fn(pageRows);
     });
+    // Page rows are a subset of the same object references already processed
+    // by injectedRows — no need to re-inject state or re-apply hooks.
     const injectedPageRows = derived(pageRows, ($pageRows) => {
         derivationCalls.injectedPageRows++;
-        // Inject state.
-        $pageRows.forEach((row) => {
-            row.injectState(tableState);
-            row.cells.forEach((cell) => {
-                cell.injectState(tableState);
-            });
-        });
-        // Apply plugin component hooks.
-        Object.entries(pluginInstances).forEach(([pluginName, pluginInstance]) => {
-            $pageRows.forEach((row) => {
-                if (pluginInstance.hooks?.['tbody.tr'] !== undefined) {
-                    row.applyHook(pluginName, pluginInstance.hooks['tbody.tr'](row));
-                }
-                row.cells.forEach((cell) => {
-                    if (pluginInstance.hooks?.['tbody.tr.td'] !== undefined) {
-                        cell.applyHook(pluginName, pluginInstance.hooks['tbody.tr.td'](cell));
-                    }
-                });
-            });
-        });
         _pageRows.set($pageRows);
         return $pageRows;
     });
     const headerRows = derived(injectedColumns, ($injectedColumns) => {
         derivationCalls.headerRows++;
         const $headerRows = getHeaderRows(columns, $injectedColumns.map((c) => c.id));
-        // Inject state.
         $headerRows.forEach((row) => {
             row.injectState(tableState);
-            row.cells.forEach((cell) => {
-                cell.injectState(tableState);
-            });
-        });
-        // Apply plugin component hooks.
-        Object.entries(pluginInstances).forEach(([pluginName, pluginInstance]) => {
-            $headerRows.forEach((row) => {
-                if (pluginInstance.hooks?.['thead.tr'] !== undefined) {
-                    row.applyHook(pluginName, pluginInstance.hooks['thead.tr'](row));
+            row.cells.forEach((cell) => cell.injectState(tableState));
+            for (const [pluginName, pluginInstance] of pluginEntries) {
+                const trHook = pluginInstance.hooks?.['thead.tr'];
+                if (trHook !== undefined) {
+                    row.applyHook(pluginName, trHook(row));
                 }
-                row.cells.forEach((cell) => {
-                    if (pluginInstance.hooks?.['thead.tr.th'] !== undefined) {
-                        cell.applyHook(pluginName, pluginInstance.hooks['thead.tr.th'](cell));
-                    }
-                });
-            });
+                const thHook = pluginInstance.hooks?.['thead.tr.th'];
+                if (thHook !== undefined) {
+                    row.cells.forEach((cell) => cell.applyHook(pluginName, thHook(cell)));
+                }
+            }
         });
         _headerRows.set($headerRows);
         return $headerRows;

package/dist/plugins/addColumnOrder.js

@@ -25,15 +25,20 @@ export const addColumnOrder = ({ initialColumnIdOrder = [], hideUnspecifiedColum
     const pluginState = { columnIdOrder };
     const deriveFlatColumns = (flatColumns) => {
         return derived([flatColumns, columnIdOrder], ([$flatColumns, $columnIdOrder]) => {
-            const _flatColumns = [...$flatColumns];
+            const colById = new Map($flatColumns.map((c) => [c.id, c]));
             const orderedFlatColumns = [];
             $columnIdOrder.forEach((id) => {
-                const colIdx = _flatColumns.findIndex((c) => c.id === id);
-                orderedFlatColumns.push(..._flatColumns.splice(colIdx, 1));
+                const col = colById.get(id);
+                if (col !== undefined) {
+                    orderedFlatColumns.push(col);
+                    colById.delete(id);
+                }
             });
             if (!hideUnspecifiedColumns) {
-                // Push the remaining unspecified columns.
-                orderedFlatColumns.push(..._flatColumns);
+                // Remaining entries preserve original $flatColumns order.
+                for (const col of colById.values()) {
+                    orderedFlatColumns.push(col);
+                }
             }
             return orderedFlatColumns;
         });

package/dist/plugins/addGroupBy.js

@@ -59,8 +59,12 @@ export const getGroupedRows = (rows, groupByIds, columnOptions, { repeatCellIds,
         if (typeof groupOnValue === 'function' || typeof groupOnValue === 'object') {
             console.warn(`Missing \`getGroupOn\` column option to aggregate column "${groupById}" with object values`);
         }
-        const subRows = subRowsForGroupOnValue.get(groupOnValue) ?? [];
-        subRowsForGroupOnValue.set(groupOnValue, [...subRows, row]);
+        let subRows = subRowsForGroupOnValue.get(groupOnValue);
+        if (subRows === undefined) {
+            subRows = [];
+            subRowsForGroupOnValue.set(groupOnValue, subRows);
+        }
+        subRows.push(row);
     }
     const groupedRows = [];
     let groupRowIdx = 0;

package/dist/plugins/addVirtualScroll.d.ts

@@ -0,0 +1,37 @@
+import type { NewTablePropSet, TablePlugin } from '../types/TablePlugin.js';
+import type { ScrollToIndexOptions, VirtualScrollConfig, VirtualScrollRowProps, VirtualScrollState, VisibleRange } from './addVirtualScroll.types.js';
+export type { ScrollToIndexOptions, VirtualScrollConfig, VirtualScrollState, VisibleRange };
+/**
+ * Creates a virtual scroll plugin that enables virtualized table rendering.
+ * Only renders rows that are visible in the viewport plus a buffer, dramatically
+ * improving performance for large datasets.
+ *
+ * @template Item - The type of data items in the table.
+ * @param config - Configuration options for virtual scrolling.
+ * @returns A TablePlugin that provides virtualization functionality.
+ *
+ * @example
+ * ```typescript
+ * const table = createTable(data, {
+ *   virtualScroll: addVirtualScroll({
+ *     estimatedRowHeight: 48,
+ *     bufferSize: 5,
+ *     onLoadMore: async () => {
+ *       const more = await fetchMoreItems()
+ *       data.update(d => [...d, ...more])
+ *     },
+ *     hasMore: hasMoreStore
+ *   })
+ * })
+ *
+ * const {
+ *   virtualScroll,
+ *   topSpacerHeight,
+ *   bottomSpacerHeight,
+ *   visibleRange
+ * } = table.pluginStates.virtualScroll
+ * ```
+ */
+export declare const addVirtualScroll: <Item>({ onLoadMore, hasMore: hasMoreConfig, loadMoreThreshold, estimatedRowHeight, bufferSize, getRowHeight }?: VirtualScrollConfig<Item>) => TablePlugin<Item, VirtualScrollState<Item>, Record<string, never>, NewTablePropSet<{
+    "tbody.tr": VirtualScrollRowProps;
+}>>;

package/dist/plugins/addVirtualScroll.js

@@ -0,0 +1,314 @@
+import { derived, get, readable, writable } from 'svelte/store';
+import { HeightManager } from '../utils/HeightManager.js';
+/**
+ * Default configuration values for virtual scroll.
+ */
+const DEFAULTS = {
+    estimatedRowHeight: 40,
+    bufferSize: 10,
+    loadMoreThreshold: 200
+};
+/**
+ * Creates a virtual scroll plugin that enables virtualized table rendering.
+ * Only renders rows that are visible in the viewport plus a buffer, dramatically
+ * improving performance for large datasets.
+ *
+ * @template Item - The type of data items in the table.
+ * @param config - Configuration options for virtual scrolling.
+ * @returns A TablePlugin that provides virtualization functionality.
+ *
+ * @example
+ * ```typescript
+ * const table = createTable(data, {
+ *   virtualScroll: addVirtualScroll({
+ *     estimatedRowHeight: 48,
+ *     bufferSize: 5,
+ *     onLoadMore: async () => {
+ *       const more = await fetchMoreItems()
+ *       data.update(d => [...d, ...more])
+ *     },
+ *     hasMore: hasMoreStore
+ *   })
+ * })
+ *
+ * const {
+ *   virtualScroll,
+ *   topSpacerHeight,
+ *   bottomSpacerHeight,
+ *   visibleRange
+ * } = table.pluginStates.virtualScroll
+ * ```
+ */
+export const addVirtualScroll = ({ onLoadMore, hasMore: hasMoreConfig, loadMoreThreshold = DEFAULTS.loadMoreThreshold, estimatedRowHeight = DEFAULTS.estimatedRowHeight, bufferSize = DEFAULTS.bufferSize, getRowHeight } = {}) => () => {
+    // Height management
+    const heightManager = new HeightManager(estimatedRowHeight);
+    // Scroll state
+    const scrollTop = writable(0);
+    const viewportHeight = writable(0);
+    // Row IDs array (set by derivePageRows, used for calculations)
+    // This is a simple array, not derived from rows to avoid circular deps
+    const rowIds = writable([]);
+    // Loading state
+    const isLoading = writable(false);
+    const hasMoreStore = typeof hasMoreConfig === 'object' && hasMoreConfig !== null
+        ? hasMoreConfig
+        : writable(hasMoreConfig ?? false);
+    // Track whether we've already triggered a load to prevent duplicates
+    let loadMorePending = false;
+    // Scroll container reference (set by the action)
+    let scrollContainer = null;
+    // Cache for row lookup (set by derivePageRows)
+    let allRowsCache = [];
+    // Visible range calculation.
+    // Return the same object reference when the range hasn't changed to avoid
+    // unnecessary downstream store updates (spacer heights, rendered rows).
+    let currentRange = { start: 0, end: 0 };
+    const visibleRange = derived([rowIds, scrollTop, viewportHeight], ([$rowIds, $scrollTop, $viewportHeight], set) => {
+        const range = heightManager.getVisibleRange($rowIds, $scrollTop, $viewportHeight, bufferSize);
+        if (range.start === currentRange.start && range.end === currentRange.end) {
+            return;
+        }
+        currentRange = range;
+        set(range);
+    }, currentRange);
+    // Total height of all rows
+    const totalHeight = derived(rowIds, ($rowIds) => {
+        return heightManager.getTotalHeight($rowIds);
+    });
+    // Spacer heights
+    const topSpacerHeight = derived([rowIds, visibleRange], ([$rowIds, $range]) => {
+        return heightManager.getOffsetForIndex($rowIds, $range.start);
+    });
+    const bottomSpacerHeight = derived([rowIds, visibleRange, totalHeight], ([$rowIds, $range, $total]) => {
+        const endOffset = heightManager.getOffsetForIndex($rowIds, $range.end);
+        return Math.max(0, $total - endOffset);
+    });
+    // Total and rendered row counts
+    const totalRows = derived(rowIds, ($rowIds) => $rowIds.length);
+    const renderedRows = derived(visibleRange, ($range) => $range.end - $range.start);
+    /**
+     * Check if we should load more data and trigger the callback.
+     */
+    const checkLoadMore = () => {
+        if (!onLoadMore || loadMorePending || !get(hasMoreStore)) {
+            return;
+        }
+        const $scrollTop = get(scrollTop);
+        const $viewportHeight = get(viewportHeight);
+        const $totalHeight = get(totalHeight);
+        const distanceFromBottom = $totalHeight - ($scrollTop + $viewportHeight);
+        if (distanceFromBottom <= loadMoreThreshold) {
+            loadMorePending = true;
+            isLoading.set(true);
+            const result = onLoadMore();
+            if (result instanceof Promise) {
+                result.finally(() => {
+                    loadMorePending = false;
+                    isLoading.set(false);
+                });
+            }
+            else {
+                loadMorePending = false;
+                isLoading.set(false);
+            }
+        }
+    };
+    /**
+     * Handle scroll events from the container.
+     */
+    const handleScroll = (event) => {
+        const target = event.target;
+        scrollTop.set(target.scrollTop);
+        checkLoadMore();
+    };
+    /**
+     * Svelte action to attach to the scroll container.
+     */
+    const virtualScroll = (node) => {
+        scrollContainer = node;
+        // Disable overflow-anchor to prevent the browser from adjusting
+        // scrollTop when spacer heights change. Without this, a feedback
+        // loop occurs: spacer change → browser adjusts scrollTop → scroll
+        // event → new visible range → spacer change → cascades to bottom.
+        node.style.overflowAnchor = 'none';
+        // Set initial viewport height
+        const initialHeight = node.clientHeight;
+        viewportHeight.set(initialHeight);
+        // Create ResizeObserver to track viewport size changes
+        const resizeObserver = new ResizeObserver((entries) => {
+            for (const entry of entries) {
+                viewportHeight.set(entry.contentRect.height);
+            }
+        });
+        resizeObserver.observe(node);
+        // Attach scroll listener
+        node.addEventListener('scroll', handleScroll, { passive: true });
+        // Check if we need to load more initially
+        checkLoadMore();
+        return {
+            destroy() {
+                scrollContainer = null;
+                node.removeEventListener('scroll', handleScroll);
+                resizeObserver.disconnect();
+            }
+        };
+    };
+    /**
+     * Scroll to a specific row index.
+     */
+    const scrollToIndex = (index, options = {}) => {
+        if (!scrollContainer) {
+            return;
+        }
+        const { align = 'start', behavior = 'auto' } = options;
+        const $rowIds = get(rowIds);
+        if (index < 0 || index >= $rowIds.length) {
+            return;
+        }
+        const targetOffset = heightManager.getOffsetForIndex($rowIds, index);
+        const rowHeight = heightManager.getHeight($rowIds[index]);
+        const $viewportHeight = get(viewportHeight);
+        let scrollPosition;
+        switch (align) {
+            case 'center':
+                scrollPosition = targetOffset - ($viewportHeight - rowHeight) / 2;
+                break;
+            case 'end':
+                scrollPosition = targetOffset - $viewportHeight + rowHeight;
+                break;
+            case 'auto': {
+                // Check if already visible
+                const $scrollTop = get(scrollTop);
+                const visibleStart = $scrollTop;
+                const visibleEnd = $scrollTop + $viewportHeight;
+                const rowStart = targetOffset;
+                const rowEnd = targetOffset + rowHeight;
+                if (rowStart >= visibleStart && rowEnd <= visibleEnd) {
+                    // Already fully visible
+                    return;
+                }
+                else if (rowStart < visibleStart) {
+                    scrollPosition = rowStart;
+                }
+                else {
+                    scrollPosition = rowEnd - $viewportHeight;
+                }
+                break;
+            }
+            case 'start':
+            default:
+                scrollPosition = targetOffset;
+                break;
+        }
+        scrollContainer.scrollTo({
+            top: Math.max(0, scrollPosition),
+            behavior
+        });
+    };
+    /**
+     * Notify the plugin that a row has been measured.
+     */
+    const measureRow = (rowId, height) => {
+        // If getRowHeight is provided, prefer that
+        if (getRowHeight) {
+            const row = allRowsCache.find((r) => r.id === rowId);
+            if (row?.isData() && row.original) {
+                const specifiedHeight = getRowHeight(row.original);
+                if (specifiedHeight !== height) {
+                    height = specifiedHeight;
+                }
+            }
+        }
+        const changed = heightManager.setHeight(rowId, height);
+        if (changed) {
+            // Force recalculation of derived stores by updating rowIds
+            // (touching it with the same value)
+            rowIds.update((v) => v);
+        }
+    };
+    /**
+     * Svelte action to automatically measure row height.
+     * Attach to each <tr> element: <tr use:measureRowAction={row.id}>
+     */
+    const measureRowAction = (node, rowId) => {
+        // Measure initial height
+        const measure = () => {
+            const height = node.getBoundingClientRect().height;
+            if (height > 0) {
+                measureRow(rowId, height);
+            }
+        };
+        // Measure on mount
+        measure();
+        // Use ResizeObserver to track height changes
+        const resizeObserver = new ResizeObserver(() => {
+            measure();
+        });
+        resizeObserver.observe(node);
+        return {
+            update(newRowId) {
+                rowId = newRowId;
+                measure();
+            },
+            destroy() {
+                resizeObserver.disconnect();
+            }
+        };
+    };
+    // Plugin state
+    const pluginState = {
+        scrollTop: { subscribe: scrollTop.subscribe },
+        viewportHeight: { subscribe: viewportHeight.subscribe },
+        visibleRange,
+        totalHeight,
+        topSpacerHeight,
+        bottomSpacerHeight,
+        isLoading: { subscribe: isLoading.subscribe },
+        hasMore: { subscribe: hasMoreStore.subscribe },
+        virtualScroll,
+        scrollToIndex,
+        measureRow,
+        measureRowAction,
+        totalRows,
+        renderedRows
+    };
+    /**
+     * Derive visible rows from all page rows.
+     * Re-runs when rows, scroll position, or viewport height changes.
+     */
+    const derivePageRows = (rows) => {
+        return derived([rows, scrollTop, viewportHeight], ([$rows, $scrollTop, $viewportHeight], set) => {
+            // Cache rows for lookup in measureRow and hooks
+            allRowsCache = $rows;
+            // Extract row IDs and update the store (only if changed)
+            const ids = $rows.map((r) => r.id);
+            const currentIds = get(rowIds);
+            if (ids.length !== currentIds.length ||
+                ids.some((id, i) => id !== currentIds[i])) {
+                rowIds.set(ids);
+            }
+            // Calculate visible range
+            const range = heightManager.getVisibleRange(ids, $scrollTop, $viewportHeight, bufferSize);
+            // Return only the visible subset
+            const visibleRows = $rows.slice(range.start, range.end);
+            set(visibleRows);
+        });
+    };
+    // Hooks to add virtual index props to rows
+    const hooks = {
+        'tbody.tr': (row) => {
+            const virtualIndex = allRowsCache.findIndex((r) => r.id === row.id);
+            return {
+                props: readable({
+                    virtualIndex: virtualIndex >= 0 ? virtualIndex : 0,
+                    isVirtual: true
+                })
+            };
+        }
+    };
+    return {
+        pluginState,
+        derivePageRows,
+        hooks
+    };
+};

package/dist/plugins/addVirtualScroll.types.d.ts

@@ -0,0 +1,139 @@
+import type { Action } from 'svelte/action';
+import type { Readable, Writable } from 'svelte/store';
+/**
+ * Configuration options for the addVirtualScroll plugin.
+ *
+ * @template Item - The type of data items in the table.
+ */
+export interface VirtualScrollConfig<Item> {
+    /**
+     * Callback fired when more data should be loaded (infinite scroll).
+     * Return a promise to indicate when loading is complete.
+     */
+    onLoadMore?: () => void | Promise<void>;
+    /**
+     * Whether there is more data available to load.
+     * Can be a boolean or a Writable store.
+     */
+    hasMore?: Writable<boolean> | boolean;
+    /**
+     * Number of pixels from the bottom to trigger onLoadMore.
+     * @default 200
+     */
+    loadMoreThreshold?: number;
+    /**
+     * Estimated height of each row in pixels.
+     * Used for initial calculations before rows are measured.
+     * @default 40
+     */
+    estimatedRowHeight?: number;
+    /**
+     * Number of rows to render above and below the visible area.
+     * Higher values reduce flicker during fast scrolling but render more DOM nodes.
+     * @default 10
+     */
+    bufferSize?: number;
+    /**
+     * Optional function to get the height of a specific row.
+     * If provided, enables variable row heights.
+     */
+    getRowHeight?: (_item: Item) => number;
+}
+/**
+ * Visible range of rows.
+ */
+export interface VisibleRange {
+    /** Index of the first visible row (0-based). */
+    start: number;
+    /** Index of the last visible row (exclusive). */
+    end: number;
+}
+/**
+ * Options for scrollToIndex method.
+ */
+export interface ScrollToIndexOptions {
+    /** Alignment of the target row within the viewport. */
+    align?: 'start' | 'center' | 'end' | 'auto';
+    /** Scroll behavior. */
+    behavior?: ScrollBehavior;
+}
+/**
+ * State exposed by the addVirtualScroll plugin.
+ *
+ * @template Item - The type of data items in the table.
+ */
+export interface VirtualScrollState<Item> {
+    /**
+     * Current scroll position of the container.
+     */
+    scrollTop: Readable<number>;
+    /**
+     * Height of the scroll container viewport.
+     */
+    viewportHeight: Readable<number>;
+    /**
+     * Range of currently visible row indices.
+     */
+    visibleRange: Readable<VisibleRange>;
+    /**
+     * Total height of all rows (for scroll container sizing).
+     */
+    totalHeight: Readable<number>;
+    /**
+     * Height of the top spacer element.
+     */
+    topSpacerHeight: Readable<number>;
+    /**
+     * Height of the bottom spacer element.
+     */
+    bottomSpacerHeight: Readable<number>;
+    /**
+     * Whether more data is currently being loaded.
+     */
+    isLoading: Readable<boolean>;
+    /**
+     * Whether there is more data available to load.
+     */
+    hasMore: Readable<boolean>;
+    /**
+     * Svelte action to attach to the scroll container.
+     * Handles scroll event listeners and viewport tracking.
+     */
+    virtualScroll: Action<HTMLElement>;
+    /**
+     * Scroll to a specific row index.
+     */
+    scrollToIndex: (_index: number, _options?: ScrollToIndexOptions) => void;
+    /**
+     * Notify the plugin that a row has been measured.
+     * Called automatically when rows are rendered.
+     * @internal
+     */
+    measureRow: (_rowId: string, _height: number) => void;
+    /**
+     * Svelte action to attach to each table row for automatic height measurement.
+     * Usage: <tr use:measureRowAction={row.id}>
+     */
+    measureRowAction: Action<HTMLElement, string>;
+    /**
+     * Total number of rows (before virtualization).
+     */
+    totalRows: Readable<number>;
+    /**
+     * Number of rows currently rendered in the DOM.
+     */
+    renderedRows: Readable<number>;
+}
+/**
+ * Props added to body rows by the virtual scroll plugin.
+ */
+export interface VirtualScrollRowProps {
+    /**
+     * Index of this row in the full dataset.
+     */
+    virtualIndex: number;
+    /**
+     * Whether this row is currently in the visible range.
+     */
+    isVirtual: boolean;
+}

package/dist/plugins/addVirtualScroll.types.js

@@ -0,0 +1 @@
+export {};

package/dist/plugins/index.d.ts

@@ -12,4 +12,5 @@ export * from './addSelectedRows';
 export * from './addSortBy';
 export * from './addSubRows';
 export * from './addTableFilter';
+export * from './addVirtualScroll';
 export * from '../types/TablePlugin';

package/dist/plugins/index.js

@@ -12,5 +12,6 @@ export * from './addSelectedRows';
 export * from './addSortBy';
 export * from './addSubRows';
 export * from './addTableFilter';
+export * from './addVirtualScroll';
 // plugin helper types
 export * from '../types/TablePlugin';

package/dist/utils/HeightManager.d.ts

@@ -0,0 +1,107 @@
+/**
+ * HeightManager handles row height caching and calculations for virtual scrolling.
+ * It maintains a cache of measured row heights and provides methods to calculate
+ * scroll positions, visible ranges, and total heights.
+ */
+export declare class HeightManager {
+    /** Cache of measured row heights by row ID. */
+    private heightCache;
+    /** Estimated height for unmeasured rows. */
+    private estimatedRowHeight;
+    /** Sum of all measured heights. */
+    private totalMeasuredHeight;
+    /** Number of measured rows. */
+    private measuredCount;
+    /**
+     * Creates a new HeightManager.
+     *
+     * @param estimatedRowHeight - Initial estimated height for unmeasured rows.
+     */
+    constructor(estimatedRowHeight?: number);
+    /**
+     * Set or update the height for a specific row.
+     *
+     * @param rowId - The unique identifier of the row.
+     * @param height - The measured height of the row in pixels.
+     * @returns True if the height changed, false otherwise.
+     */
+    setHeight(rowId: string, height: number): boolean;
+    /**
+     * Get the height for a specific row.
+     * Returns the measured height if available, otherwise the estimated height.
+     *
+     * @param rowId - The unique identifier of the row.
+     * @returns The height of the row in pixels.
+     */
+    getHeight(rowId: string): number;
+    /**
+     * Check if a row has been measured.
+     *
+     * @param rowId - The unique identifier of the row.
+     * @returns True if the row has been measured.
+     */
+    hasMeasurement(rowId: string): boolean;
+    /**
+     * Get the average height of measured rows.
+     * Falls back to the estimated height if no rows have been measured.
+     *
+     * @returns The average row height in pixels.
+     */
+    getAverageHeight(): number;
+    /**
+     * Calculate the total height for a given number of rows.
+     *
+     * @param rowIds - Array of row IDs in order.
+     * @returns The total height in pixels.
+     */
+    getTotalHeight(rowIds: string[]): number;
+    /**
+     * Calculate the offset (top position) for a given row index.
+     *
+     * @param rowIds - Array of row IDs in order.
+     * @param index - The index of the target row.
+     * @returns The offset from the top in pixels.
+     */
+    getOffsetForIndex(rowIds: string[], index: number): number;
+    /**
+     * Calculate which rows are visible given a scroll position and viewport height.
+     *
+     * @param rowIds - Array of row IDs in order.
+     * @param scrollTop - Current scroll position.
+     * @param viewportHeight - Height of the visible area.
+     * @param bufferSize - Number of extra rows to render above/below.
+     * @returns Object with start and end indices of visible rows.
+     */
+    getVisibleRange(rowIds: string[], scrollTop: number, viewportHeight: number, bufferSize: number): {
+        start: number;
+        end: number;
+    };
+    /**
+     * Find the row index at a given scroll position.
+     *
+     * @param rowIds - Array of row IDs in order.
+     * @param scrollTop - The scroll position to find.
+     * @returns The index of the row at that position.
+     */
+    getIndexAtOffset(rowIds: string[], scrollTop: number): number;
+    /**
+     * Clear all cached heights.
+     */
+    clear(): void;
+    /**
+     * Remove a specific row from the cache.
+     *
+     * @param rowId - The unique identifier of the row to remove.
+     */
+    remove(rowId: string): void;
+    /**
+     * Get the number of measured rows.
+     */
+    get size(): number;
+    /**
+     * Update the estimated row height.
+     *
+     * @param height - New estimated height in pixels.
+     */
+    setEstimatedRowHeight(height: number): void;
+}

package/dist/utils/HeightManager.js

@@ -0,0 +1,204 @@
+/**
+ * HeightManager handles row height caching and calculations for virtual scrolling.
+ * It maintains a cache of measured row heights and provides methods to calculate
+ * scroll positions, visible ranges, and total heights.
+ */
+export class HeightManager {
+    /** Cache of measured row heights by row ID. */
+    heightCache = new Map();
+    /** Estimated height for unmeasured rows. */
+    estimatedRowHeight;
+    /** Sum of all measured heights. */
+    totalMeasuredHeight = 0;
+    /** Number of measured rows. */
+    measuredCount = 0;
+    /**
+     * Creates a new HeightManager.
+     *
+     * @param estimatedRowHeight - Initial estimated height for unmeasured rows.
+     */
+    constructor(estimatedRowHeight = 40) {
+        this.estimatedRowHeight = estimatedRowHeight;
+    }
+    /**
+     * Set or update the height for a specific row.
+     *
+     * @param rowId - The unique identifier of the row.
+     * @param height - The measured height of the row in pixels.
+     * @returns True if the height changed, false otherwise.
+     */
+    setHeight(rowId, height) {
+        const existing = this.heightCache.get(rowId);
+        if (existing === height) {
+            return false;
+        }
+        if (existing !== undefined) {
+            // Update existing measurement
+            this.totalMeasuredHeight -= existing;
+            this.totalMeasuredHeight += height;
+        }
+        else {
+            // New measurement
+            this.totalMeasuredHeight += height;
+            this.measuredCount++;
+        }
+        this.heightCache.set(rowId, height);
+        return true;
+    }
+    /**
+     * Get the height for a specific row.
+     * Returns the measured height if available, otherwise the estimated height.
+     *
+     * @param rowId - The unique identifier of the row.
+     * @returns The height of the row in pixels.
+     */
+    getHeight(rowId) {
+        return this.heightCache.get(rowId) ?? this.getAverageHeight();
+    }
+    /**
+     * Check if a row has been measured.
+     *
+     * @param rowId - The unique identifier of the row.
+     * @returns True if the row has been measured.
+     */
+    hasMeasurement(rowId) {
+        return this.heightCache.has(rowId);
+    }
+    /**
+     * Get the average height of measured rows.
+     * Falls back to the estimated height if no rows have been measured.
+     *
+     * @returns The average row height in pixels.
+     */
+    getAverageHeight() {
+        if (this.measuredCount === 0) {
+            return this.estimatedRowHeight;
+        }
+        return this.totalMeasuredHeight / this.measuredCount;
+    }
+    /**
+     * Calculate the total height for a given number of rows.
+     *
+     * @param rowIds - Array of row IDs in order.
+     * @returns The total height in pixels.
+     */
+    getTotalHeight(rowIds) {
+        const avgHeight = this.getAverageHeight();
+        let total = 0;
+        for (const rowId of rowIds) {
+            total += this.heightCache.get(rowId) ?? avgHeight;
+        }
+        return total;
+    }
+    /**
+     * Calculate the offset (top position) for a given row index.
+     *
+     * @param rowIds - Array of row IDs in order.
+     * @param index - The index of the target row.
+     * @returns The offset from the top in pixels.
+     */
+    getOffsetForIndex(rowIds, index) {
+        const avgHeight = this.getAverageHeight();
+        let offset = 0;
+        for (let i = 0; i < index && i < rowIds.length; i++) {
+            offset += this.heightCache.get(rowIds[i]) ?? avgHeight;
+        }
+        return offset;
+    }
+    /**
+     * Calculate which rows are visible given a scroll position and viewport height.
+     *
+     * @param rowIds - Array of row IDs in order.
+     * @param scrollTop - Current scroll position.
+     * @param viewportHeight - Height of the visible area.
+     * @param bufferSize - Number of extra rows to render above/below.
+     * @returns Object with start and end indices of visible rows.
+     */
+    getVisibleRange(rowIds, scrollTop, viewportHeight, bufferSize) {
+        if (rowIds.length === 0) {
+            return { start: 0, end: 0 };
+        }
+        const avgHeight = this.getAverageHeight();
+        let offset = 0;
+        let start = 0;
+        let end = rowIds.length;
+        // Find start index (first row that's at least partially visible)
+        for (let i = 0; i < rowIds.length; i++) {
+            const height = this.heightCache.get(rowIds[i]) ?? avgHeight;
+            if (offset + height > scrollTop) {
+                start = Math.max(0, i - bufferSize);
+                break;
+            }
+            offset += height;
+        }
+        // Find end index (first row that's completely below the viewport)
+        const bottomEdge = scrollTop + viewportHeight;
+        for (let i = start; i < rowIds.length; i++) {
+            const height = this.heightCache.get(rowIds[i]) ?? avgHeight;
+            if (offset >= bottomEdge) {
+                end = Math.min(rowIds.length, i + bufferSize);
+                break;
+            }
+            offset += height;
+        }
+        // If we reached the end without finding bottomEdge, show all remaining rows
+        if (end === rowIds.length) {
+            end = rowIds.length;
+        }
+        return { start, end };
+    }
+    /**
+     * Find the row index at a given scroll position.
+     *
+     * @param rowIds - Array of row IDs in order.
+     * @param scrollTop - The scroll position to find.
+     * @returns The index of the row at that position.
+     */
+    getIndexAtOffset(rowIds, scrollTop) {
+        const avgHeight = this.getAverageHeight();
+        let offset = 0;
+        for (let i = 0; i < rowIds.length; i++) {
+            const height = this.heightCache.get(rowIds[i]) ?? avgHeight;
+            if (offset + height > scrollTop) {
+                return i;
+            }
+            offset += height;
+        }
+        return Math.max(0, rowIds.length - 1);
+    }
+    /**
+     * Clear all cached heights.
+     */
+    clear() {
+        this.heightCache.clear();
+        this.totalMeasuredHeight = 0;
+        this.measuredCount = 0;
+    }
+    /**
+     * Remove a specific row from the cache.
+     *
+     * @param rowId - The unique identifier of the row to remove.
+     */
+    remove(rowId) {
+        const height = this.heightCache.get(rowId);
+        if (height !== undefined) {
+            this.totalMeasuredHeight -= height;
+            this.measuredCount--;
+            this.heightCache.delete(rowId);
+        }
+    }
+    /**
+     * Get the number of measured rows.
+     */
+    get size() {
+        return this.measuredCount;
+    }
+    /**
+     * Update the estimated row height.
+     *
+     * @param height - New estimated height in pixels.
+     */
+    setEstimatedRowHeight(height) {
+        this.estimatedRowHeight = height;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-headless-table",
-  "version": "6.0.3",
+  "version": "6.0.5",
   "description": "A powerful, headless table library for Svelte that provides complete control over table UI while handling complex data operations like sorting, filtering, pagination, grouping, and row expansion. Build custom, accessible data tables with zero styling opinions.",
   "keywords": [
     "svelte",
@@ -58,47 +58,46 @@
     "!dist/**/*.spec.*"
   ],
   "dependencies": {
-    "@humanspeak/memory-cache": "^1.0.4",
+    "@humanspeak/memory-cache": "^1.0.5",
     "@humanspeak/svelte-keyed": "^5.0.1",
     "@humanspeak/svelte-render": "^5.1.1",
     "@humanspeak/svelte-subscribe": "^5.0.0"
   },
   "devDependencies": {
     "@eslint/compat": "^2.0.2",
-    "@eslint/js": "^9.39.2",
-    "@faker-js/faker": "^10.2.0",
-    "@playwright/test": "^1.58.1",
-    "@sveltejs/adapter-auto": "^7.0.0",
-    "@sveltejs/kit": "^2.50.1",
+    "@eslint/js": "^10.0.1",
+    "@faker-js/faker": "^10.3.0",
+    "@playwright/test": "^1.58.2",
+    "@sveltejs/adapter-auto": "^7.0.1",
+    "@sveltejs/kit": "^2.53.4",
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/svelte": "^5.3.1",
     "@types/eslint": "9.6.1",
-    "@types/node": "^25.1.0",
-    "@typescript-eslint/eslint-plugin": "^8.54.0",
-    "@typescript-eslint/parser": "^8.54.0",
+    "@types/node": "^25.3.3",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
     "@vitest/coverage-v8": "^4.0.18",
-    "concurrently": "^9.2.1",
-    "eslint": "^9.39.2",
+    "eslint": "^10.0.2",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-import": "2.32.0",
-    "eslint-plugin-svelte": "3.14.0",
-    "eslint-plugin-unused-imports": "4.3.0",
-    "globals": "^17.2.0",
+    "eslint-plugin-svelte": "3.15.0",
+    "eslint-plugin-unused-imports": "4.4.1",
+    "globals": "^17.4.0",
     "husky": "^9.1.7",
     "prettier": "^3.8.1",
     "prettier-plugin-organize-imports": "^4.3.0",
     "prettier-plugin-sort-json": "^4.2.0",
-    "prettier-plugin-svelte": "^3.4.1",
+    "prettier-plugin-svelte": "^3.5.1",
     "prettier-plugin-tailwindcss": "^0.7.2",
-    "publint": "^0.3.17",
-    "svelte": "^5.49.1",
-    "svelte-check": "^4.3.5",
+    "publint": "^0.3.18",
+    "svelte": "^5.53.7",
+    "svelte-check": "^4.4.4",
     "tslib": "^2.8.1",
-    "type-fest": "^5.4.2",
+    "type-fest": "^5.4.4",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.54.0",
+    "typescript-eslint": "^8.56.1",
     "vite": "^7.3.1",
     "vitest": "^4.0.18"
   },
@@ -106,7 +105,7 @@
     "svelte": "^5.30.0"
   },
   "volta": {
-    "node": "24.12.0"
+    "node": "24.14.0"
   },
   "scripts": {
     "build": "vite build && npm run package",
@@ -114,7 +113,7 @@
     "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
     "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
     "dev": "vite dev",
-    "dev:all": "concurrently -k -n pkg,docs,sitemap -c green,cyan,magenta \"pnpm -w -r --filter @humanspeak/svelte-headless-table run dev:pkg\" \"pnpm --filter docs run dev\" \"pnpm --filter docs run sitemap:watch\"",
+    "dev:all": "mprocs",
     "dev:pkg": "svelte-kit sync && svelte-package --watch",
     "format": "prettier --write .",
     "lint": "prettier --check . && eslint .",