@svgrid/grid 3.0.7 → 3.0.9

package/dist/virtualization/virtualizer.js

@@ -5,6 +5,8 @@ function sameOptions(a, b) {
     return (a.count === b.count &&
         a.estimateSize === b.estimateSize &&
         (a.overscan ?? 6) === (b.overscan ?? 6) &&
+        a.overscanBehind === b.overscanBehind &&
+        a.overscanMin === b.overscanMin &&
         a.viewportHeight === b.viewportHeight &&
         (a.scrollOffset ?? 0) === (b.scrollOffset ?? 0));
 }
@@ -107,11 +109,12 @@ function buildVariableItems(startIndex, endIndex, offsets) {
     }
     return items;
 }
-function createState(options, 
+/** The items under the viewport at the current scroll offset, before any
+ *  overscan. */
+function visibleRange(options, 
 /** Pre-built cumulative offsets for the variable-size path. */
 offsets) {
     const count = Math.max(options.count, 0);
-    const overscan = Math.max(options.overscan ?? 6, 0);
     const viewportHeight = Math.max(options.viewportHeight, 0);
     if (typeof options.estimateSize === 'function' && offsets) {
         const totalSize = offsets[count] ?? 0;
@@ -140,29 +143,47 @@ offsets) {
                 hi = mid;
         }
         const visibleEnd = Math.max(lo - 1, visibleStart);
-        const startIndex = count === 0 ? 0 : clamp(visibleStart - overscan, 0, count - 1);
-        const endIndex = count === 0 ? -1 : clamp(visibleEnd + overscan, 0, count - 1);
-        return {
-            items: endIndex >= startIndex ? buildVariableItems(startIndex, endIndex, offsets) : [],
-            totalSize,
-            startIndex,
-            endIndex,
-            scrollOffset,
-            viewportHeight,
-        };
+        return { count, viewportHeight, totalSize, scrollOffset, visibleStart, visibleEnd, uniformSize: 0 };
     }
     // Uniform-size fast path (original behavior).
-    const estimateSize = Math.max(typeof options.estimateSize === 'number' ? options.estimateSize : 1, 1);
-    const totalSize = count * estimateSize;
+    const uniformSize = Math.max(typeof options.estimateSize === 'number' ? options.estimateSize : 1, 1);
+    const totalSize = count * uniformSize;
     const maxOffset = Math.max(totalSize - viewportHeight, 0);
     const scrollOffset = clamp(options.scrollOffset ?? 0, 0, maxOffset);
-    const visibleStart = Math.floor(scrollOffset / estimateSize);
-    const visibleCount = Math.ceil(viewportHeight / estimateSize);
+    const visibleStart = Math.floor(scrollOffset / uniformSize);
+    const visibleCount = Math.ceil(viewportHeight / uniformSize);
     const visibleEnd = Math.min(visibleStart + visibleCount, Math.max(count - 1, 0));
-    const startIndex = count === 0 ? 0 : clamp(visibleStart - overscan, 0, count - 1);
-    const endIndex = count === 0 ? -1 : clamp(visibleEnd + overscan, 0, count - 1);
+    return { count, viewportHeight, totalSize, scrollOffset, visibleStart, visibleEnd, uniformSize };
+}
+function createState(options, 
+/** Pre-built cumulative offsets for the variable-size path. */
+offsets, 
+/** The scroll moved on from the window already rendered. With
+ *  `overscanMin`, only then does the full `overscan` go ahead; a window
+ *  built at rest or after a jump carries `overscanMin`, so a thumb drag
+ *  that jumps every frame renders no more than it needs. */
+scrolling = false) {
+    const full = Math.max(options.overscan ?? 6, 0);
+    const overscan = options.overscanMin === undefined || scrolling ? full : clamp(options.overscanMin, 0, full);
+    // The overscan goes ahead of the scroll and `overscanBehind` behind it:
+    // items behind the movement were just scrolled past, and a horizontal
+    // scroll that kept three columns on each side drew ~40% more cells than it
+    // needed to (350 vs 275 in the wide benchmark).
+    const behind = Math.min(Math.max(options.overscanBehind ?? full, 0), overscan);
+    const direction = options.scrollDirection ?? 0;
+    const overscanBefore = direction > 0 ? behind : overscan;
+    const overscanAfter = direction < 0 ? behind : overscan;
+    const { count, viewportHeight, totalSize, scrollOffset, visibleStart, visibleEnd, uniformSize } = visibleRange(options, offsets);
+    const startIndex = count === 0 ? 0 : clamp(visibleStart - overscanBefore, 0, count - 1);
+    const endIndex = count === 0 ? -1 : clamp(visibleEnd + overscanAfter, 0, count - 1);
+    let items = [];
+    if (endIndex >= startIndex) {
+        items = uniformSize > 0
+            ? buildUniformItems(startIndex, endIndex, uniformSize)
+            : buildVariableItems(startIndex, endIndex, offsets);
+    }
     return {
-        items: endIndex >= startIndex ? buildUniformItems(startIndex, endIndex, estimateSize) : [],
+        items,
         totalSize,
         startIndex,
         endIndex,
@@ -200,13 +221,54 @@ export function createVirtualizer(initial) {
     function emit() {
         listeners.forEach((listener) => listener());
     }
-    function recalc() {
-        const next = createState(options, getOffsets());
+    function recalc(scrolling = false) {
+        const next = createState(options, getOffsets(), scrolling);
         if (sameState(state, next))
             return;
+        // Hand back the previous item object for a row whose index, offset, size
+        // and slot did not change. The grid's row {#each} is keyed by slot, so a
+        // row that stays in the window keeps its <tr>, but a new item object
+        // still invalidated everything that row and its cells derive from it:
+        // every scroll frame re-checked ~300 cells to render the two that came
+        // into view, and Svelte's dependency marking was most of the frame's
+        // script time (measured 4.8 of 8.3 ms on a 100k-row grid).
+        if (state.items.length > 0 && next.items.length > 0) {
+            const first = state.items[0].index;
+            const items = next.items;
+            for (let i = 0; i < items.length; i += 1) {
+                const item = items[i];
+                const prev = state.items[item.index - first];
+                if (prev && prev.index === item.index && prev.start === item.start && prev.size === item.size && prev.key === item.key) {
+                    items[i] = prev;
+                }
+            }
+        }
         state = next;
         emit();
     }
+    /**
+     * What a scroll does to the window already rendered, with `overscanMin`:
+     * 'hold' while that window still covers the visible items plus
+     * `overscanMin` ahead of the scroll, 'move' once the scroll runs past that
+     * (the window moves on with the full overscan ahead), and 'jump' when the
+     * visible items are nowhere in it. Without `overscanMin` every scroll moves
+     * the window.
+     */
+    function scrollStep() {
+        const min = options.overscanMin;
+        if (min === undefined || state.items.length === 0)
+            return 'move';
+        const ahead = clamp(min, 0, Math.max(options.overscan ?? 6, 0));
+        const { count, viewportHeight, totalSize, visibleStart, visibleEnd } = visibleRange(options, getOffsets());
+        if (count === 0 || viewportHeight !== state.viewportHeight || totalSize !== state.totalSize)
+            return 'jump';
+        if (visibleStart > state.endIndex || visibleEnd < state.startIndex)
+            return 'jump';
+        const direction = options.scrollDirection ?? 0;
+        const needStart = Math.max(visibleStart - (direction < 0 ? ahead : 0), 0);
+        const needEnd = Math.min(visibleEnd + (direction > 0 ? ahead : 0), count - 1);
+        return state.startIndex <= needStart && state.endIndex >= needEnd ? 'hold' : 'move';
+    }
     return {
         setOptions(next) {
             const merged = { ...options, ...next };
@@ -229,10 +291,14 @@ export function createVirtualizer(initial) {
             recalc();
         },
         setScrollOffset(scrollOffset) {
-            if ((options.scrollOffset ?? 0) === scrollOffset)
+            const previous = options.scrollOffset ?? 0;
+            if (previous === scrollOffset)
                 return;
-            options = { ...options, scrollOffset };
-            recalc();
+            options = { ...options, scrollOffset, scrollDirection: scrollOffset > previous ? 1 : -1 };
+            const step = scrollStep();
+            if (step === 'hold')
+                return;
+            recalc(step === 'move');
         },
         setViewportHeight(viewportHeight) {
             if (options.viewportHeight === viewportHeight)

package/dist/windowed-brand.d.ts

@@ -0,0 +1,22 @@
+/**
+ * What marks an array as windowed data, and how to tell (windowed-data.ts has
+ * the full story). Kept apart from createWindowedData so code that only asks
+ * "is this windowed?" - the controller, the core's per-update paths - does not
+ * pull in the windowed row model that createWindowedData installs.
+ */
+export type WindowedSource<T> = {
+    /** The number of rows, loaded or not. */
+    readonly length: number;
+    /** The entry at `index`: a loaded row, a placeholder, or undefined. */
+    at(index: number): T | undefined;
+};
+/**
+ * An array of `length` entries read through `at(i)`: a real `Array` (a Proxy
+ * over an empty one) carrying the windowed mark. Each call returns a new
+ * array identity, which is how a source tells the grid its rows changed.
+ */
+export declare function makeWindowedArray<T>(length: number, at: (index: number) => T | undefined): T[];
+/** The source behind windowed data, or null for an ordinary array. */
+export declare function windowedSourceOf<T>(data: unknown): WindowedSource<T> | null;
+/** True for windowed data. */
+export declare function isWindowedData(data: unknown): boolean;

package/dist/windowed-brand.js

@@ -0,0 +1,60 @@
+/**
+ * What marks an array as windowed data, and how to tell (windowed-data.ts has
+ * the full story). Kept apart from createWindowedData so code that only asks
+ * "is this windowed?" - the controller, the core's per-update paths - does not
+ * pull in the windowed row model that createWindowedData installs.
+ */
+const WINDOWED = Symbol.for('svgrid.windowedData');
+const isIndexKey = (key) => typeof key === 'string' && key.length > 0 && key.length < 16 && /^(0|[1-9]\d*)$/.test(key);
+/**
+ * An array of `length` entries read through `at(i)`: a real `Array` (a Proxy
+ * over an empty one) carrying the windowed mark. Each call returns a new
+ * array identity, which is how a source tells the grid its rows changed.
+ */
+export function makeWindowedArray(length, at) {
+    const source = { length, at };
+    const target = [];
+    return new Proxy(target, {
+        get(t, key, receiver) {
+            if (key === WINDOWED)
+                return source;
+            if (key === 'length')
+                return length;
+            if (isIndexKey(key)) {
+                const i = Number(key);
+                return i < length ? at(i) : undefined;
+            }
+            return Reflect.get(t, key, receiver);
+        },
+        has(t, key) {
+            if (key === WINDOWED)
+                return true;
+            if (isIndexKey(key))
+                return Number(key) < length;
+            return Reflect.has(t, key);
+        },
+        set() {
+            // Read-only: a write would land in the empty target and never be seen.
+            return false;
+        },
+        getOwnPropertyDescriptor(t, key) {
+            if (isIndexKey(key) && Number(key) < length) {
+                return { value: at(Number(key)), writable: false, enumerable: true, configurable: true };
+            }
+            if (key === 'length')
+                return { value: length, writable: true, enumerable: false, configurable: false };
+            return Reflect.getOwnPropertyDescriptor(t, key);
+        },
+    });
+}
+/** The source behind windowed data, or null for an ordinary array. */
+export function windowedSourceOf(data) {
+    if (data === null || typeof data !== 'object')
+        return null;
+    const source = data[WINDOWED];
+    return source ?? null;
+}
+/** True for windowed data. */
+export function isWindowedData(data) {
+    return windowedSourceOf(data) !== null;
+}

package/dist/windowed-data.d.ts

@@ -0,0 +1,6 @@
+export { windowedSourceOf, isWindowedData, type WindowedSource } from './windowed-brand.js';
+/**
+ * An array of `length` entries read through `at(i)`. Each call returns a new
+ * array identity, which is how a source tells the grid its rows changed.
+ */
+export declare function createWindowedData<T>(length: number, at: (index: number) => T | undefined): T[];

package/dist/windowed-data.js

@@ -0,0 +1,34 @@
+/**
+ * Windowed data: an array the grid can index without anyone having built it.
+ *
+ * A server row model knows how many rows there are and holds a few blocks of
+ * them. Handing the grid a dense array of `rowCount` entries (placeholders
+ * for everything not loaded) made every block landing cost O(rowCount): the
+ * array itself, a copy in the controller, and a row object per entry in the
+ * core. At 10M rows that was ~1 GB of heap and ~1 s per block; at 100M the
+ * grid never painted.
+ *
+ * `createWindowedData(length, at)` returns a real `Array` (a Proxy over one)
+ * whose `length` is the row count and whose entries are read through `at(i)`
+ * on demand. The grid recognises it (`windowedSourceOf`) and builds row
+ * objects only for the indices it actually reads - the rows on screen, plus
+ * whatever a user action touches. Iterating one still works (it is an array),
+ * but costs O(length), so the grid's per-update paths check for it first.
+ *
+ * Windowed data is final: the source has already sorted, filtered and grouped
+ * it, so the grid's own sort / filter / group stages do not run over it.
+ *
+ * The row model that reads it (windowed-row-model.ts) is installed by the
+ * first call here, so a grid never handed windowed data does not bundle it.
+ */
+import { makeWindowedArray } from './windowed-brand.js';
+import { enableWindowedRowModel } from './windowed-row-model.js';
+export { windowedSourceOf, isWindowedData } from './windowed-brand.js';
+/**
+ * An array of `length` entries read through `at(i)`. Each call returns a new
+ * array identity, which is how a source tells the grid its rows changed.
+ */
+export function createWindowedData(length, at) {
+    enableWindowedRowModel();
+    return makeWindowedArray(length, at);
+}

package/dist/windowed-row-model.d.ts

@@ -0,0 +1 @@
+export declare function enableWindowedRowModel(): void;

package/dist/windowed-row-model.js

@@ -0,0 +1,97 @@
+/**
+ * The row model for windowed data (see windowed-data.ts).
+ *
+ * No build loop and no pipeline stages: `rows` is itself windowed. A row
+ * object is made the first time an index is read and kept (up to
+ * WINDOWED_ROW_CAP) while its data object is the same one, so scrolling back
+ * does not rebuild what is still loaded, and scrolling a 100M-row source end
+ * to end keeps a few thousand rows, not 100M.
+ *
+ * Installed into the core by the first createWindowedData() call rather than
+ * imported by core.ts, so a grid that is never handed windowed data does not
+ * bundle any of this.
+ */
+import { BASE_ROW_METHODS, ROW_CELLS, ROW_CTX, ROW_FILTER_GEN, ROW_FILTER_POS, ROW_SORT_DROPPED, ROW_SORT_KEY, ROW_VALUES, registerWindowedRowModel, } from './core.js';
+import { makeWindowedArray, windowedSourceOf } from './windowed-brand.js';
+/** The windowed-data version a row's memoised values belong to. */
+const ROW_WINDOW_GEN = Symbol('svgrid.row.windowGen');
+const WINDOWED_ROW_CAP = 20000;
+let installed = false;
+export function enableWindowedRowModel() {
+    if (installed)
+        return;
+    installed = true;
+    registerWindowedRowModel((ctx) => {
+        // Per grid: the model for the current input, and the row objects built
+        // so far, by index.
+        let current = null;
+        const rows = new Map();
+        let generation = 0;
+        return (data, columns) => {
+            const source = windowedSourceOf(data);
+            if (!source)
+                return null;
+            if (current && current.input === data && current.columns === columns)
+                return current.model;
+            if (!current || current.columns !== columns)
+                rows.clear();
+            const rowCtx = ctx.rowCtxFor(columns);
+            const getRowId = ctx.getRowId();
+            const gen = ++generation;
+            const m = BASE_ROW_METHODS;
+            const rowAt = (index) => {
+                if (index < 0 || index >= source.length)
+                    return undefined;
+                const original = source.at(index);
+                if (original === undefined)
+                    return undefined;
+                const kept = rows.get(index);
+                if (kept && kept.original === original) {
+                    // A new data version may follow an in-place edit of the object, as
+                    // in the dense path: drop the memoised values once per version.
+                    if (kept[ROW_WINDOW_GEN] !== gen) {
+                        kept[ROW_VALUES] = null;
+                        kept[ROW_CELLS] = null;
+                        kept[ROW_WINDOW_GEN] = gen;
+                    }
+                    return kept;
+                }
+                const row = {
+                    id: getRowId ? getRowId(original, index) : String(index),
+                    index,
+                    original,
+                    depth: 0,
+                    [ROW_CTX]: rowCtx,
+                    [ROW_VALUES]: null,
+                    [ROW_CELLS]: null,
+                    [ROW_FILTER_GEN]: 0,
+                    [ROW_FILTER_POS]: -1,
+                    [ROW_SORT_DROPPED]: 0,
+                    [ROW_SORT_KEY]: undefined,
+                    [ROW_WINDOW_GEN]: gen,
+                    getCanExpand: m.getCanExpand,
+                    getIsExpanded: m.getIsExpanded,
+                    toggleExpanded: m.toggleExpanded,
+                    getIsSelected: m.getIsSelected,
+                    toggleSelected: m.toggleSelected,
+                    getAllCells: m.getAllCells,
+                    getCellValueByColumnId: m.getCellValueByColumnId,
+                };
+                rows.set(index, row);
+                if (rows.size > WINDOWED_ROW_CAP) {
+                    // Oldest first (Map keeps insertion order); a quarter at a time.
+                    let drop = WINDOWED_ROW_CAP / 4;
+                    for (const key of rows.keys()) {
+                        if (drop-- <= 0)
+                            break;
+                        rows.delete(key);
+                    }
+                }
+                return row;
+            };
+            const model = { rows: makeWindowedArray(source.length, rowAt) };
+            current = { input: data, columns, model };
+            return model;
+        };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svgrid/grid",
-  "version": "3.0.7",
+  "version": "3.0.9",
   "description": "Svelte 5-native data grid and data table. Headless-first engine with virtual scrolling for 100k+ rows, Excel-style filtering, inline editing, grouping, tree data, pivot, and server-side data. Drop-in <SvGrid> component. TypeScript, SSR-ready.",
   "author": "jQWidgets <boikom@jqwidgets.com>",
   "license": "MIT",

package/src/GridMenus.svelte

@@ -49,7 +49,6 @@
   const unpinColumn = $derived(ctrl.unpinColumn);
   const sortDirectionByColumn = $derived(ctrl.sortDirectionByColumn);
   const groupingColumns = $derived(ctrl.groupingColumns);
-  const columnVirtualizationEnabled = $derived(ctrl.columnVirtualizationEnabled);
   const updateFilterOperator = $derived(ctrl.updateFilterOperator);
   const updateFilterMenuValue = $derived(ctrl.updateFilterMenuValue);
   const updateFilterMenuValueTo = $derived(ctrl.updateFilterMenuValueTo);
@@ -644,7 +643,9 @@
           <span class="sv-grid-header-icon">{@render icon("x")}</span> Remove sort
         </button>
       {/if}
-      {#if !columnVirtualizationEnabled}
+      <!-- Pinning works with column virtualization on: the pinned columns render
+           as their own runs either side of the virtual window. -->
+      {#if menuColumnId}
         {@const menuPinSide = isColumnPinned(menuColumnId)}
         <div class="sv-grid-menu-sep"></div>
         <button