@svgrid/grid 3.0.7 → 3.0.9

package/dist/filtering/excel-filters.js

@@ -151,6 +151,41 @@ function scanInTokens(value) {
 // pull in SvGrid.svelte, which is a runtime cost (and a bundler hazard) for
 // anything that only wants operator semantics.
 export { ALL_FILTER_OPERATORS, SET_OPERATOR_IDS, VALUELESS_OPERATOR_IDS, RANGE_OPERATOR_IDS, isSetOperator, isValuelessOperator, isRangeOperator, } from './filter-operator-catalogue.js';
+/**
+ * A text test, remembered per distinct cell text.
+ *
+ * The text operators fold every cell (lowercase, and for non-ASCII text NFD
+ * plus diacritic stripping) before comparing, and a column the user filters
+ * is usually a category - region, status, owner - with a handful of distinct
+ * values over every row. Folding each row again was most of a 1M-row filter
+ * (417 ms). The answer depends only on the cell's text, so it is kept per
+ * text. A column that turns out mostly unique (more than half of the first
+ * 2,048 lookups missed) stops remembering and tests directly, and the memo
+ * never grows past MEMO_CAP entries.
+ */
+const MEMO_CAP = 16384;
+function memoText(test) {
+    let memo = new Map();
+    let lookups = 0;
+    let hits = 0;
+    return (cellValue) => {
+        const s = typeof cellValue === 'string' ? cellValue : String(cellValue ?? '');
+        if (memo === null)
+            return test(s);
+        lookups++;
+        const known = memo.get(s);
+        if (known !== undefined) {
+            hits++;
+            return known;
+        }
+        const result = test(s);
+        if (memo.size < MEMO_CAP)
+            memo.set(s, result);
+        if (lookups >= 2048 && hits * 2 < lookups)
+            memo = null;
+        return result;
+    };
+}
 /**
  * Compile a filter once, then test many rows against it.
  *
@@ -168,23 +203,23 @@ export function compileExcelFilter(filter, options) {
     const needle = fold(filter.value);
     switch (filter.operator) {
         case 'contains':
-            return (cellValue) => fold(cellValue).includes(needle);
+            return memoText((s) => fold(s).includes(needle));
         case 'notContains':
             // An empty needle is no constraint (mirrors `contains` returning true),
             // so nothing is excluded until the user types something.
             if (needle === '')
                 return () => true;
-            return (cellValue) => !fold(cellValue).includes(needle);
+            return memoText((s) => !fold(s).includes(needle));
         case 'equals':
-            return (cellValue) => fold(cellValue) === needle;
+            return memoText((s) => fold(s) === needle);
         case 'notEquals':
             if (needle === '')
                 return () => true;
-            return (cellValue) => fold(cellValue) !== needle;
+            return memoText((s) => fold(s) !== needle);
         case 'startsWith':
-            return (cellValue) => fold(cellValue).startsWith(needle);
+            return memoText((s) => fold(s).startsWith(needle));
         case 'endsWith':
-            return (cellValue) => fold(cellValue).endsWith(needle);
+            return memoText((s) => fold(s).endsWith(needle));
         case 'regex': {
             // Case-insensitive by default (matches the accent/case-folded feel of
             // the other text operators). An invalid pattern matches nothing rather

package/dist/headless.d.ts

@@ -26,7 +26,7 @@
 export { columnFilteringFeature, columnGroupingFeature, createCoreRowModel, createExpandedRowModel, createFilteredRowModel, createGroupedRowModel, createPaginatedRowModel, createSortedRowModel, createTreeRowModel, createSvGridCore, flattenTreeData, applyGroupAggregate, filterFns, rowExpandingFeature, rowPaginationFeature, rowSelectionFeature, rowSortingFeature, sortFns, tableFeatures, type Cell, type CellContext, type CellSpanParams, type ValueParserParams, type EditorContext, type CellData, type ActiveCellState, type CellFormatConfig, type CellFormatter, type Column, type ColumnDef, type ColumnDefTemplate, type ColumnFilter, type ColumnFiltersState, type ExpandedState, type GridColumnDef, type GridColumns, type GroupAggregator, type GroupingState, type Header, type HeaderContext, type HeaderGroup, type PaginationState, type Row, type RowData, type RowModel, type RowModelFactory, type RowSelectionState, type SortingState, type Store, type SvGrid as SvGridInstance, type SvGridOptions, type TableFeatures, type TreeRowModelOptions, type FlattenTreeOptions, type Updater, } from './core.js';
 export { createGrid, createSvGrid, type SvelteGrid } from './createGrid.svelte.js';
 export { createGridState, createSvGridState } from './createGridState.svelte.js';
-export { subscribeGrid, subscribeSvGrid } from './subscribe.js';
+export { subscribeGrid, subscribeSvGrid } from './subscribe.svelte.js';
 export { createVirtualizer } from './virtualization/virtualizer.js';
 export { createSvelteVirtualizer } from './virtualization/svelte-virtualizer.svelte.js';
 export { createColumnVirtualizer } from './virtualization/column-virtualizer.js';

package/dist/headless.js

@@ -26,7 +26,7 @@
 export { columnFilteringFeature, columnGroupingFeature, createCoreRowModel, createExpandedRowModel, createFilteredRowModel, createGroupedRowModel, createPaginatedRowModel, createSortedRowModel, createTreeRowModel, createSvGridCore, flattenTreeData, applyGroupAggregate, filterFns, rowExpandingFeature, rowPaginationFeature, rowSelectionFeature, rowSortingFeature, sortFns, tableFeatures, } from './core.js';
 export { createGrid, createSvGrid } from './createGrid.svelte.js';
 export { createGridState, createSvGridState } from './createGridState.svelte.js';
-export { subscribeGrid, subscribeSvGrid } from './subscribe.js';
+export { subscribeGrid, subscribeSvGrid } from './subscribe.svelte.js';
 // The virtualizers are pure window arithmetic (scroll offset in, visible
 // range out) with no DOM of their own, and a custom renderer over 50k rows
 // needs one. They were only on the barrel, so the Headless demos imported

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { coerceExportDate, formatValueForExport, projectGridRows, toExcelNumFmt,
 export { columnFilteringFeature, columnGroupingFeature, createCoreRowModel, createExpandedRowModel, createFilteredRowModel, createGroupedRowModel, createPaginatedRowModel, createSortedRowModel, createTreeRowModel, flattenTreeData, applyGroupAggregate, filterFns, rowExpandingFeature, rowPaginationFeature, rowSelectionFeature, rowSortingFeature, sortFns, tableFeatures, type Cell, type CellContext, type CellSpanParams, type ValueParserParams, type EditorContext, type CellData, type ActiveCellState, type CellFormatConfig, type CellFormatter, type Column, type ColumnDef, type ColumnDefTemplate, type GridColumnDef, type GridColumns, type GroupAggregator, type Header, type HeaderContext, type HeaderGroup, type Row, type RowData, type SortingState, type SvGrid as SvGridInstance, type SvGridOptions, type TableFeatures, type TreeRowModelOptions, type FlattenTreeOptions, type Updater, } from './core.js';
 export { createGrid, createSvGrid, type SvelteGrid } from './createGrid.svelte.js';
 export { createGridState, createSvGridState } from './createGridState.svelte.js';
-export { subscribeGrid, subscribeSvGrid } from './subscribe.js';
+export { subscribeGrid, subscribeSvGrid } from './subscribe.svelte.js';
 export { default as SvGrid } from './SvGrid.svelte';
 export type { BoardConfig, BoardLane, BoardCardMoveEvent, BoardCardCommitEvent, BoardLayout, BoardSubtask, BoardComment, BoardMenuContext, BoardLaneMenuContext, BoardDrawerConfig } from './SvGrid.types.js';
 export { registerBoardView, getBoardView, hasBoardView } from './board-view.svelte.js';
@@ -215,6 +215,7 @@ export { createHyperFormulaSheet, type HyperFormulaSheet, type HyperFormulaSheet
 export { createCollaboration, broadcastChannelTransport, type CollabUser, type CollabCell, type CollabPresence, type CollabMessage, type CollabTransport, type Collaboration, } from './collaboration.js';
 export { createServerDataSource, type ServerDataSource, type ServerSelectionRule, type ServerRequest, type ServerResult, type ServerController, type ServerControllerOptions, type ServerState, type ServerSortModel, type ServerFilterModel, type ServerAggFn, type ServerAggregation, type ServerGroupRow, type ServerLeafRow, type ServerMoreRow, type ServerFooterRow, type ServerSkeletonRow, type ServerGrandTotalRow, type ServerPlaceholderRow, type ServerDisplayRow, type ServerDetailRow, } from './server-data-source.js';
 export { createBlockCache, createRowPlaceholder, rowPlaceholderState, type BlockCache, type BlockCacheOptions, type BlockCacheState, type BlockFetchResult, type BlockState, } from './server-block-cache.js';
+export { createWindowedData, windowedSourceOf, isWindowedData, type WindowedSource, } from './windowed-data.js';
 export { toServerFilterColumns, type GridRowModel, type GridFilterState, type GridRowModelSort, } from './row-model.js';
 export { createNamedViews, memoryViews, localStorageViews, attachAutoSavedView, type SavedView, type ViewStorage, type NamedViews, type AutoSavedViewOptions, } from './named-views.js';
 export { resolveCellFormat, computeColumnStat, lerpColor, rgba, contrastText, formatNeedsStats, formatsNeedingStats, type ConditionalFormat, type ConditionalFormatSpec, type ColorScaleFormat, type ColorScaleStop, type ScaleBounds, type DataBarFormat, type IconSetFormat, type RuleFormat, type ResolvedCellFormat, } from './conditional-formatting.js';

package/dist/index.js

@@ -3,7 +3,7 @@ export { coerceExportDate, formatValueForExport, projectGridRows, toExcelNumFmt,
 export { columnFilteringFeature, columnGroupingFeature, createCoreRowModel, createExpandedRowModel, createFilteredRowModel, createGroupedRowModel, createPaginatedRowModel, createSortedRowModel, createTreeRowModel, flattenTreeData, applyGroupAggregate, filterFns, rowExpandingFeature, rowPaginationFeature, rowSelectionFeature, rowSortingFeature, sortFns, tableFeatures, } from './core.js';
 export { createGrid, createSvGrid } from './createGrid.svelte.js';
 export { createGridState, createSvGridState } from './createGridState.svelte.js';
-export { subscribeGrid, subscribeSvGrid } from './subscribe.js';
+export { subscribeGrid, subscribeSvGrid } from './subscribe.svelte.js';
 export { default as SvGrid } from './SvGrid.svelte';
 export { registerBoardView, getBoardView, hasBoardView } from './board-view.svelte.js';
 // Built-in AI helpers (free): natural-language filter, smart-fill, summarize,
@@ -255,6 +255,7 @@ export { createHyperFormulaSheet, } from './hyperformula-adapter.js';
 export { createCollaboration, broadcastChannelTransport, } from './collaboration.js';
 export { createServerDataSource, } from './server-data-source.js';
 export { createBlockCache, createRowPlaceholder, rowPlaceholderState, } from './server-block-cache.js';
+export { createWindowedData, windowedSourceOf, isWindowedData, } from './windowed-data.js';
 export { toServerFilterColumns, } from './row-model.js';
 export { createNamedViews, memoryViews, localStorageViews, attachAutoSavedView, } from './named-views.js';
 export { resolveCellFormat, computeColumnStat, lerpColor, rgba, contrastText, formatNeedsStats, formatsNeedingStats, } from './conditional-formatting.js';

package/dist/keyboard-handlers.js

@@ -189,7 +189,11 @@ export function createKeyboard(ctx) {
                 }
             }
             if (column?.columnDef.editorType === "checkbox") {
-                ctx.toggleBooleanCell(current.rowIndex, current.colIndex);
+                // Same rule as a click: `editable: false` (or an editable callback
+                // saying no) keeps the checkbox read-only.
+                if (ctx.isCellEditableAt?.(current.rowIndex, current.colIndex) ?? true) {
+                    ctx.toggleBooleanCell(current.rowIndex, current.colIndex);
+                }
                 return;
             }
             ctx.onCellDoubleClick(current.rowIndex, current.colIndex);

package/dist/selection.d.ts

@@ -1,8 +1,8 @@
 import { type RowData, type TableFeatures } from "./index.js";
 import "./sv-grid-scrollbar.js";
 export declare function createSelection<TFeatures extends TableFeatures = TableFeatures, TData extends RowData = RowData>(ctx: any): {
-    isRowSelected: (rowId: string) => any;
-    toggleRowSelectionById: (rowId: string) => void;
+    isRowSelected: (rowId: string, original?: unknown) => any;
+    toggleRowSelectionById: (rowId: string, original?: unknown) => void;
     toggleSelectAllRows: () => void;
     setSelectAllRows: (select: boolean) => void;
     setActiveCell: (rowIndex: number, colIndex: number) => void;

package/dist/selection.js

@@ -6,21 +6,33 @@ import "./sv-grid-scrollbar.js";
 import { getColumnBaseValue, isGroupRow, } from "./cell-values.js";
 import { expandRectToMerges, originOf, endOf } from "./merges.js";
 export function createSelection(ctx) {
-    function isRowSelected(rowId) {
+    /**
+     * A selection model needs the row's data. The body passes the row it is
+     * drawing as `original`; without it the row is looked up by id, a scan of
+     * every row - on a server model's windowed million rows, once per drawn
+     * row, that scan held the page for seconds after a sort.
+     */
+    function rowOriginal(rowId) {
+        const row = ctx.allRows.find((r) => r.id === rowId);
+        return row ? { found: true, original: row.original } : { found: false };
+    }
+    function isRowSelected(rowId, original) {
         const model = ctx.props.rowSelectionModel;
         if (model) {
-            const row = ctx.allRows.find((r) => r.id === rowId);
-            return row ? model.isSelected(rowId, row.original) : false;
+            if (original !== undefined)
+                return model.isSelected(rowId, original);
+            const hit = rowOriginal(rowId);
+            return hit.found ? model.isSelected(rowId, hit.original) : false;
         }
         return Boolean(ctx.rowSelectionState[rowId]);
     }
-    function toggleRowSelectionById(rowId) {
+    function toggleRowSelectionById(rowId, original) {
         const model = ctx.props.rowSelectionModel;
         if (model) {
-            const row = ctx.allRows.find((r) => r.id === rowId);
-            if (!row)
+            const hit = original !== undefined ? { found: true, original } : rowOriginal(rowId);
+            if (!hit.found)
                 return;
-            model.toggle(rowId, row.original, !model.isSelected(rowId, row.original));
+            model.toggle(rowId, hit.original, !model.isSelected(rowId, hit.original));
             return;
         }
         ctx.grid.setRowSelection((prev) => ({ ...prev, [rowId]: !prev[rowId] }));
@@ -446,8 +458,20 @@ export function createSelection(ctx) {
     }
     /** Look up a column by id without depending on `buildApi`'s private
      *  closure (those helpers don't exist at this scope). */
+    // id -> column, rebuilt when the column list changes. Called per header
+    // cell as columns scroll into view, so a linear `find` made every scroll
+    // frame cost more the more columns the grid has.
+    let columnsById = new Map();
+    let columnsByIdFor = null;
     function findColumnById(columnId) {
-        return ctx.allColumns.find((c) => c.id === columnId);
+        const all = ctx.allColumns;
+        if (all !== columnsByIdFor) {
+            columnsById = new Map();
+            for (const c of all)
+                columnsById.set(c.id, c);
+            columnsByIdFor = all;
+        }
+        return columnsById.get(columnId);
     }
     function onCellPointerDown(rowIndex, colIndex, event) {
         if (event.button !== 0)
@@ -622,10 +646,20 @@ export function createSelection(ctx) {
             columnId: column.id,
             row: row.original,
         });
-        const isCheckboxColumn = column.columnDef.editorType === "checkbox" ||
-            typeof cellValue === "boolean";
-        if (isCheckboxColumn) {
-            ctx.toggleBooleanCell(rowIndex, colIndex);
+        // A declared checkbox editor toggles on click unless the cell is not
+        // editable. A value that only HAPPENS to be boolean is drawn as a read-only
+        // checkbox, so it toggles only when inline editing is on - it used to flip
+        // and write the row on any click, in grids with editing switched off. A
+        // column with its own `cell` renderer draws (and handles) the value itself.
+        const declaredCheckbox = column.columnDef.editorType === "checkbox";
+        const inferredCheckbox = !declaredCheckbox &&
+            typeof cellValue === "boolean" &&
+            column.columnDef.cell == null;
+        if (declaredCheckbox || inferredCheckbox) {
+            const editable = ctx.isCellEditableAt?.(rowIndex, colIndex) ?? true;
+            if (editable && (declaredCheckbox || ctx.editingEnabled)) {
+                ctx.toggleBooleanCell(rowIndex, colIndex);
+            }
             setActiveCell(rowIndex, colIndex);
             setSelection(rowIndex, colIndex);
             ctx.editingCell = null;

package/dist/server-block-cache.d.ts

@@ -1,35 +1,3 @@
-/**
- * Block cache for server-backed rows - the engine behind infinite scrolling.
- *
- * Paging asks for "page 3". Infinite scrolling asks a different question: the
- * user is looking at rows 4,000 to 4,020 of a table with a million rows, so
- * fetch the block that covers them, keep a bounded number of recently-seen
- * blocks, and render something sensible for every row nobody has fetched yet.
- * That is all this module does, in plain TypeScript with no Svelte and no DOM.
- *
- * The shape of the problem (and most of the vocabulary) is the same one every
- * grid with a server row model solves, so the options here are deliberately
- * recognisable: `blockSize`, `maxBlocksInCache`, `maxConcurrentRequests`,
- * `blockLoadDebounceMs`, `initialRowCount`, `overflowRows`.
- *
- * Three things it takes seriously:
- *
- *   - **Unloaded rows still have to render.** `rows()` always returns a dense
- *     array, with a shared sentinel object in every slot that has no data. The
- *     grid recognises those (see {@link rowPlaceholderState}) and draws a
- *     skeleton or a retry affordance instead of an empty row, so the scrollbar
- *     never lies and scrolling never leaves a hole.
- *   - **The row count may be unknown.** A backend that cannot cheaply count
- *     says so (omit `rowCount`, or send `-1`) and the list grows by a block at
- *     a time until a short block proves where the end is.
- *   - **Requests are not free.** In-flight blocks are deduplicated, at most
- *     `maxConcurrentRequests` are open at once, a fast scroll debounces rather
- *     than firing a request per frame, and blocks abandoned by eviction or
- *     purge are aborted.
- *
- * Enterprise's server row model runs one of these per group level; the free
- * flat controller runs exactly one.
- */
 /**
  * The mark that says "this row is not data yet".
  *
@@ -155,6 +123,13 @@ export type BlockCache<TData> = {
     setViewport(startIndex: number, endIndex: number): void;
     /** The dense row array to hand the grid. Placeholders fill unloaded slots. */
     rows(): ReadonlyArray<TData>;
+    /**
+     * The same rows as windowed data (see windowed-data.ts): `length` is the
+     * row count and each entry is read through `getRow` when the grid asks for
+     * it, so handing it over costs O(1) whatever the count. A new array per
+     * change, like `rows()`.
+     */
+    windowedRows(): ReadonlyArray<TData>;
     /** One row, without building the array. Returns a placeholder when unloaded. */
     getRow(index: number): TData | typeof LOADING_ROW | typeof FAILED_ROW;
     rowCount(): number | null;

package/dist/server-block-cache.js

@@ -30,6 +30,7 @@
  * Enterprise's server row model runs one of these per group level; the free
  * flat controller runs exactly one.
  */
+import { createWindowedData } from './windowed-data.js';
 /**
  * The mark that says "this row is not data yet".
  *
@@ -99,6 +100,7 @@ export function createBlockCache(options) {
     let debounceTimer = null;
     let emitScheduled = false;
     let rowsCache = null;
+    let windowedCache = null;
     const blockOf = (rowIndex) => Math.floor(rowIndex / blockSize);
     const startOf = (blockIndex) => blockIndex * blockSize;
     /**
@@ -156,7 +158,7 @@ export function createBlockCache(options) {
      * mutations notifies once. Every mutating path ends here.
      */
     function emit() {
-        rowsCache = null; // rebuilt lazily, on the next read
+        rowsCache = windowedCache = null; // rebuilt lazily, on the next read
         if (disposed || emitScheduled)
             return;
         emitScheduled = true;
@@ -281,6 +283,15 @@ export function createBlockCache(options) {
                 ensureBlock(i);
         }
     }
+    function rowAt(index) {
+        const block = blocks.get(blockOf(index));
+        if (!block)
+            return LOADING_ROW;
+        if (block.status === 'failed')
+            return FAILED_ROW;
+        const row = block.rows[index - startOf(blockOf(index))];
+        return row ?? LOADING_ROW;
+    }
     function abortAll() {
         for (const block of blocks.values())
             block.controller?.abort();
@@ -330,15 +341,13 @@ export function createBlockCache(options) {
             rowsCache = out;
             return out;
         },
-        getRow(index) {
-            const block = blocks.get(blockOf(index));
-            if (!block)
-                return LOADING_ROW;
-            if (block.status === 'failed')
-                return FAILED_ROW;
-            const row = block.rows[index - startOf(blockOf(index))];
-            return row ?? LOADING_ROW;
+        windowedRows() {
+            if (windowedCache)
+                return windowedCache;
+            windowedCache = createWindowedData(currentLength(), (i) => rowAt(i));
+            return windowedCache;
         },
+        getRow: rowAt,
         rowCount: () => (countKnown ? count : null),
         lastRowKnown: () => countKnown,
         retryFailed() {
@@ -376,7 +385,7 @@ export function createBlockCache(options) {
             blocks.clear();
             count = null;
             countKnown = false;
-            rowsCache = null;
+            rowsCache = windowedCache = null;
             fetchViewport();
             emit();
         },
@@ -524,7 +533,7 @@ export function createBlockCache(options) {
                 controller: null,
             });
         }
-        rowsCache = null;
+        rowsCache = windowedCache = null;
     }
     /** Forget every block from `fromBlock` on, aborting any in flight. */
     function dropLoadedFrom(fromBlock) {
@@ -534,6 +543,6 @@ export function createBlockCache(options) {
             block.controller?.abort();
             blocks.delete(index);
         }
-        rowsCache = null;
+        rowsCache = windowedCache = null;
     }
 }

package/dist/server-data-source.js

@@ -53,7 +53,9 @@ export function createServerDataSource(source, options) {
     function emitFromCache() {
         if (!cache || disposed)
             return;
-        const rows = cache.rows();
+        // Windowed: the grid reads only the rows it shows, so a block landing
+        // costs the same at 100M rows as at 10K.
+        const rows = cache.windowedRows();
         state.rows = rows;
         state.rowCount = cache.rowCount();
         state.lastRowKnown = cache.lastRowKnown();

package/dist/server.d.ts

@@ -10,4 +10,5 @@
  */
 export { createServerDataSource, type ServerDataSource, type ServerSelectionRule, type ServerRequest, type ServerResult, type ServerController, type ServerControllerOptions, type ServerState, type ServerSortModel, type ServerFilterModel, type ServerAggFn, type ServerAggregation, type ServerGroupRow, type ServerLeafRow, type ServerMoreRow, type ServerFooterRow, type ServerSkeletonRow, type ServerGrandTotalRow, type ServerPlaceholderRow, type ServerDisplayRow, type ServerDetailRow, } from './server-data-source.js';
 export { createBlockCache, createRowPlaceholder, rowPlaceholderState, type BlockCache, type BlockCacheOptions, type BlockCacheState, type BlockFetchResult, type BlockState, } from './server-block-cache.js';
+export { createWindowedData, windowedSourceOf, isWindowedData, type WindowedSource, } from './windowed-data.js';
 export { toServerFilterColumns, type GridRowModel, type GridFilterState, type GridRowModelSort, } from './row-model.js';

package/dist/server.js

@@ -10,4 +10,5 @@
  */
 export { createServerDataSource, } from './server-data-source.js';
 export { createBlockCache, createRowPlaceholder, rowPlaceholderState, } from './server-block-cache.js';
+export { createWindowedData, windowedSourceOf, isWindowedData, } from './windowed-data.js';
 export { toServerFilterColumns, } from './row-model.js';

package/dist/spreadsheet.js

@@ -88,6 +88,13 @@ const OVERLAY_CLASS = 'sv-cell-border-overlay';
  *  every relevant DOM mutation inside the grid, and whenever the action
  *  options update. */
 function apply(root, opts) {
+    // Merges here are colspan / rowspan on the rendered cells, which only the
+    // table algorithm honours: keep this grid's rows in table layout (the
+    // flex-row rules in SvGrid.css skip a table marked this way).
+    for (const table of root.querySelectorAll('table.sv-grid-table')) {
+        if (table.getAttribute('data-row-layout') !== 'table')
+            table.setAttribute('data-row-layout', 'table');
+    }
     // ---- 1. Clean up anything the LAST run added -----------------------
     for (const td of root.querySelectorAll(`td[${MARK}]`)) {
         td.removeAttribute('colspan');

package/dist/{subscribe.js → subscribe.svelte.js}

@@ -16,7 +16,11 @@ const shallowCompare = (a, b) => {
  * comparison. Call from `<script>` so the selector is contextually typed.
  */
 export function subscribeGrid(grid, selector) {
-    let current = selector(grid.store.state);
+    // $state, not a plain variable: core.ts keeps a deliberately framework-free
+    // store, so this Svelte adapter is where reactivity belongs. Without it a
+    // `$derived` reading .current never re-runs and the docs' headless examples
+    // render their seeded state forever.
+    let current = $state(selector(grid.store.state));
     grid.store.subscribe(() => {
         const next = selector(grid.store.state);
         if (!shallowCompare(current, next))

package/dist/validate.js

@@ -1,6 +1,8 @@
 import { rowPlaceholderState } from './server-block-cache.js';
 /** How many rows to sample when deciding whether a `field` exists. */
 const FIELD_SAMPLE_ROWS = 10;
+/** How many rows to look through for that sample, placeholders included. */
+const FIELD_SCAN_ROWS = 1000;
 const DOCS = 'https://svgrid.com/docs/getting-started/3-data-and-columns/';
 /** Every leaf column, flattened through group columns. */
 function leaves(columns, out = []) {
@@ -23,10 +25,15 @@ export function validateGridConfig(input) {
     // no data keys at all and say nothing about the columns.
     // Stops at the sample size: this runs on every data change, and a filter
     // over all the rows first was O(n) per tick on a live feed.
+    // The scan is bounded too: a row model scrolled to the middle of a million
+    // rows, or just purged by a sort, hands over a list that is placeholders
+    // up to the loaded block, and walking all of them for ten real rows was
+    // O(n) per block landing. Finding none means nothing to judge by.
     const sample = [];
-    for (const row of input.data ?? []) {
-        if (sample.length >= FIELD_SAMPLE_ROWS)
-            break;
+    const data = input.data ?? [];
+    const scan = Math.min(data.length, FIELD_SCAN_ROWS);
+    for (let i = 0; i < scan && sample.length < FIELD_SAMPLE_ROWS; i += 1) {
+        const row = data[i];
         if (!rowPlaceholderState(row))
             sample.push(row);
     }
@@ -148,17 +155,9 @@ export function validateGridConfig(input) {
             'so summary bars will under-report. Remove `treeData` and set ' +
             '`gantt.parentField` instead.');
     }
-    // ---- 7. Pinning that column virtualization will hide ----------------------
-    // Documented incompatibility: the virtualizer recycles column DOM nodes, so
-    // sticky pinning cannot survive it. `columnVirtualization` defaults to ON,
-    // which means the natural way to write this silently does nothing.
-    const pinned = (input.initialColumnPinning?.left?.length ?? 0) +
-        (input.initialColumnPinning?.right?.length ?? 0);
-    if (pinned > 0 && input.columnVirtualization !== false) {
-        messages.push('[svgrid] `initialColumnPinning` is set while column virtualization is on ' +
-            '(its default), so the pinned columns will not stick - the virtualizer ' +
-            'recycles column nodes. Add `columnVirtualization={false}`.');
-    }
+    // (7. was "pinning versus column virtualization". Pinned columns now render
+    // as their own runs beside the virtual window, so the pair is supported and
+    // there is nothing to warn about.)
     // ---- 8. Server-mode contracts left half-wired -----------------------------
     // Each of these makes the grid hand control to the consumer. Miss the other
     // half and the feature looks broken rather than unconfigured.

package/dist/virtualization/column-virtualizer.d.ts

@@ -4,6 +4,10 @@ export declare function createColumnVirtualizer(input: {
     viewportWidth: number;
     scrollOffset?: number;
     overscan?: number;
+    /** Columns kept behind the scroll direction; defaults to `overscan`. */
+    overscanBehind?: number;
+    /** Fewest columns left ahead of a scroll before the window moves. */
+    overscanMin?: number;
     /** Either a uniform size (number) or a per-column size function. */
     estimateSize?: number | ColumnSizeEstimator;
 }): {

package/dist/virtualization/column-virtualizer.js

@@ -6,6 +6,8 @@ export function createColumnVirtualizer(input) {
         viewportHeight: input.viewportWidth,
         scrollOffset: input.scrollOffset ?? 0,
         overscan: input.overscan ?? 4,
+        overscanBehind: input.overscanBehind,
+        overscanMin: input.overscanMin,
     });
     return {
         ...virtualizer,

package/dist/virtualization/types.d.ts

@@ -15,8 +15,28 @@ export type VirtualizerOptions = {
      */
     estimateSize: number | ((index: number) => number);
     overscan?: number;
+    /**
+     * Items kept on the side the scroll is moving away from (`overscan` is kept
+     * ahead of it). Defaults to `overscan`, a symmetric window. Before the
+     * first scroll there is no direction and both sides get `overscan`.
+     */
+    overscanBehind?: number;
+    /**
+     * Keep the rendered window while a scroll leaves at least this many items
+     * rendered ahead of it, and move the window only when the scroll runs past
+     * that: the window is then rebuilt with the full `overscan` ahead, so it
+     * moves `overscan - overscanMin + 1` items at a time instead of one. Each
+     * move costs about the same whether one item enters or several, so fewer,
+     * larger moves are less work, and the scroll frames in between change
+     * nothing. A window built at rest, or after a jump to items outside the
+     * rendered window, carries `overscanMin` instead of `overscan`. Undefined
+     * moves the window on every item boundary, always with `overscan`.
+     */
+    overscanMin?: number;
     viewportHeight: number;
     scrollOffset?: number;
+    /** Internal: the sign of the last scroll movement (-1, 0, 1). */
+    scrollDirection?: number;
 };
 export type VirtualizerState = {
     items: Array<VirtualItem>;