@svgrid/grid 3.0.3 → 4.0.0

package/dist/selection.d.ts

@@ -1,9 +1,10 @@
 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) => boolean;
+    isRowSelected: (rowId: string) => any;
     toggleRowSelectionById: (rowId: string) => void;
     toggleSelectAllRows: () => void;
+    setSelectAllRows: (select: boolean) => void;
     setActiveCell: (rowIndex: number, colIndex: number) => void;
     scrollActiveCellIntoView: (rowIndex: number, colIndex: number) => void;
     setSelection: (rowIndex: number, colIndex: number, additive?: boolean) => void;
@@ -15,6 +16,22 @@ export declare function createSelection<TFeatures extends TableFeatures = TableF
         left: boolean;
         right: boolean;
     } | null;
+    activeRangeRect: () => {
+        minRow: number;
+        maxRow: number;
+        minCol: number;
+        maxCol: number;
+    } | null;
+    cellSelectionState: (rowIndex: number, colIndex: number) => {
+        active: boolean;
+        edges: {
+            top: boolean;
+            bottom: boolean;
+            left: boolean;
+            right: boolean;
+        } | null;
+        fillHandle: boolean;
+    } | null;
     fillMarqueeEdges: (rowIndex: number, colIndex: number) => {
         top: boolean;
         bottom: boolean;

package/dist/selection.js

@@ -4,16 +4,44 @@
 import { getGridCellDomId, } from "./index.js";
 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) {
+        const model = ctx.props.rowSelectionModel;
+        if (model) {
+            const row = ctx.allRows.find((r) => r.id === rowId);
+            return row ? model.isSelected(rowId, row.original) : false;
+        }
         return Boolean(ctx.rowSelectionState[rowId]);
     }
     function toggleRowSelectionById(rowId) {
+        const model = ctx.props.rowSelectionModel;
+        if (model) {
+            const row = ctx.allRows.find((r) => r.id === rowId);
+            if (!row)
+                return;
+            model.toggle(rowId, row.original, !model.isSelected(rowId, row.original));
+            return;
+        }
         ctx.grid.setRowSelection((prev) => ({ ...prev, [rowId]: !prev[rowId] }));
     }
     function toggleSelectAllRows() {
-        const selectable = ctx.allRows.filter((row) => !isGroupRow(row));
-        const select = ctx.headerSelectionState !== "all";
+        setSelectAllRows(ctx.headerSelectionState !== "all");
+    }
+    /**
+     * Select or clear every row, for the header checkbox and for
+     * `api.selectAllRows()`.
+     */
+    function setSelectAllRows(select) {
+        // An external model decides what "all" means - possibly a million rows
+        // the grid has never seen - so it gets the intent, not a row list.
+        if (ctx.props.rowSelectionModel) {
+            ctx.props.rowSelectionModel.toggleAll(select);
+            return;
+        }
+        // Placeholder rows are excluded: there is no row there to select yet,
+        // and ticking one would leave a selected id that never resolves.
+        const selectable = ctx.allRows.filter((row) => !isGroupRow(row) && !ctx.placeholderStateOf(row));
         ctx.grid.setRowSelection((prev) => {
             const next = { ...prev };
             for (const row of selectable) {
@@ -26,7 +54,18 @@ export function createSelection(ctx) {
         });
     }
     function setActiveCell(rowIndex, colIndex) {
+        // The active cell inside a merge is its origin: the one that draws, the
+        // one the formula bar shows, the one an edit writes.
+        ({ rowIndex, colIndex } = originOf(ctx.mergeIndex, rowIndex, colIndex));
         ctx.userHasActivatedCell = true;
+        // A click, an arrow, a jump: the Tab run is over. The Tab and Enter
+        // paths put the origin back after this call when it should live on.
+        // Activating the cell the cursor is already on (typing into it, F2, a
+        // double-click) is not a move and keeps the run.
+        const prev = ctx.grid.getState().activeCell;
+        if (!prev || prev.rowIndex !== rowIndex || prev.colIndex !== colIndex) {
+            ctx.tabRunOrigin = null;
+        }
         ctx.grid.setActiveCell({
             rowIndex,
             colIndex,
@@ -51,7 +90,16 @@ export function createSelection(ctx) {
             return;
         if (colIndex < 0 || colIndex >= ctx.allColumns.length)
             return;
-        if (ctx.rowVirtualizationEnabled) {
+        const container = ctx.scrollContainer;
+        const topBefore = container.scrollTop;
+        const leftBefore = container.scrollLeft;
+        // A frozen row is always in view; only the column may need to move.
+        const frozen = ctx.frozenRowCount ?? 0;
+        const frozenBand = ctx.frozenBandHeight ?? 0;
+        if (rowIndex < frozen) {
+            // Always in view; only the column below may need to move.
+        }
+        else if (ctx.rowVirtualizationEnabled) {
             // Prefer the browser's native `scrollIntoView({ block: 'nearest' })`
             // when the target row is already mounted. It does Excel-style
             // minimum-scroll, respects the sticky thead via the
@@ -99,8 +147,10 @@ export function createSelection(ctx) {
                 const rowHeight = ctx.virtualizer.getSizeForIndex(rowIndex);
                 const rowBottom = rowTopScroll + rowHeight;
                 let nextTop = currentTop;
-                if (rowTopScroll < currentTop + headerHeight) {
-                    nextTop = rowTopScroll - headerHeight;
+                // The frozen band sits under the header, so a row is hidden until
+                // it clears both.
+                if (rowTopScroll < currentTop + headerHeight + frozenBand) {
+                    nextTop = rowTopScroll - headerHeight - frozenBand;
                 }
                 else if (rowBottom > currentTop + clientHeight) {
                     nextTop = rowBottom - clientHeight;
@@ -154,34 +204,65 @@ export function createSelection(ctx) {
         else if (cellEnd > viewEnd) {
             ctx.scrollContainer.scrollLeft = cellEnd - ctx.scrollContainer.clientWidth;
         }
-        // No inline scrollVersion bump - the `scroll` event triggers
-        // onBodyScroll which flushes via rAF, doing one batched update.
+        // The scroll position is known right here, so hand it to the
+        // virtualizers now rather than waiting for the `scroll` event + rAF:
+        // that put the new row window one painted frame behind the active-cell
+        // move (see `syncScrollNow`). Reading the position back is cheap - the
+        // scrollIntoView / scrollTop writes above already laid the tree out.
+        const topAfter = container.scrollTop;
+        const leftAfter = container.scrollLeft;
+        if (topAfter !== topBefore || leftAfter !== leftBefore) {
+            ctx.syncScrollNow(topAfter, leftAfter);
+        }
     }
-    // Normalize a range to a rectangle, or null when incomplete.
+    // Normalize a range to a rectangle, or null when incomplete. A merge
+    // the rectangle touches is in it whole, as a spreadsheet's selection
+    // has it: a merged cell is one cell.
     function rangeRect(range) {
         const a = range?.anchor;
         const f = range?.focus;
         if (!a || !f)
             return null;
-        return {
+        return expandRectToMerges(ctx.mergeIndex, {
             minRow: Math.min(a.rowIndex, f.rowIndex),
             maxRow: Math.max(a.rowIndex, f.rowIndex),
             minCol: Math.min(a.colIndex, f.colIndex),
             maxCol: Math.max(a.colIndex, f.colIndex),
-        };
+        });
     }
+    /** The active range as a rectangle, or null while nothing is anchored. */
+    function activeRangeRect() {
+        return rangeRect(ctx.selectionRange);
+    }
+    // Memo for `getSelectionRects`, keyed on the identity of its two inputs.
+    // Both are replaced wholesale on every change and never mutated in place,
+    // so identity is a complete change check. Without it, every rendered
+    // cell's outline derived rebuilt this array on every arrow key - ~300
+    // arrays plus their rect objects per key press, for a result that is the
+    // same until the selection moves.
+    let rectsForRange = null;
+    let rectsForRanges = null;
+    let rectsMemo = [];
     // Every selected rectangle: the committed extra ranges plus the active one.
     // Order matters for copy (added-order); the active range comes last.
+    // Callers must treat the result as read-only.
     function getSelectionRects() {
+        const range = ctx.selectionRange;
+        const ranges = ctx.selectionRanges ?? [];
+        if (range === rectsForRange && ranges === rectsForRanges)
+            return rectsMemo;
         const rects = [];
-        for (const r of ctx.selectionRanges ?? []) {
+        for (const r of ranges) {
             const rect = rangeRect(r);
             if (rect)
                 rects.push(rect);
         }
-        const active = rangeRect(ctx.selectionRange);
+        const active = rangeRect(range);
         if (active)
             rects.push(active);
+        rectsForRange = range;
+        rectsForRanges = ranges;
+        rectsMemo = rects;
         return rects;
     }
     function setSelection(rowIndex, colIndex, additive = false) {
@@ -240,6 +321,9 @@ export function createSelection(ctx) {
         // that work to return null every time.
         if (!hasAnySelectionRect())
             return null;
+        // A td inside a merge draws to the merge's far corner, so its bottom and
+        // right edges are the merge's, not the cell's.
+        const end = endOf(ctx.mergeIndex, rowIndex, colIndex);
         for (const rect of getSelectionRects()) {
             if (rowIndex < rect.minRow ||
                 rowIndex > rect.maxRow ||
@@ -249,13 +333,39 @@ export function createSelection(ctx) {
             }
             return {
                 top: rowIndex === rect.minRow,
-                bottom: rowIndex === rect.maxRow,
+                bottom: end.rowIndex === rect.maxRow,
                 left: colIndex === rect.minCol,
-                right: colIndex === rect.maxCol,
+                right: end.colIndex === rect.maxCol,
             };
         }
         return null;
     }
+    /**
+     * Everything a cell's outline needs from the selection model, in ONE value:
+     * whether it is the active cell, which range edges it sits on (`edges` is
+     * null when it is in no range) and whether it carries the fill handle.
+     * `null` for a cell that is none of those - nearly every cell.
+     *
+     * One value on purpose. The view reads it through a single `{@const}`, so
+     * an active-cell move re-marks one derived per rendered cell instead of
+     * three (active flag, range edges, fill handle) plus the fill handle's
+     * `{#if}`. With ~300 cells rendered, that marking was the largest single
+     * cost of an arrow key that does not scroll. A plain cell returns the same
+     * `null` it returned before the move, so its attribute effect stays put.
+     */
+    function cellSelectionState(rowIndex, colIndex) {
+        const a = ctx.activeCell;
+        const active = !!a && a.rowIndex === rowIndex && a.colIndex === colIndex;
+        const edges = getCellRangeEdges(rowIndex, colIndex);
+        const fh = ctx.fillHandleCell;
+        // The handle sits on the range's bottom-right cell; when that is inside
+        // a merge, the td that draws the merge carries it.
+        const end = fh ? endOf(ctx.mergeIndex, rowIndex, colIndex) : null;
+        const fillHandle = !!fh && !!end && fh.rowIndex === end.rowIndex && fh.colIndex === end.colIndex;
+        if (!active && !edges && !fillHandle)
+            return null;
+        return { active, edges, fillHandle };
+    }
     /**
      * The rectangle a drag is currently promising, or null when no drag is in
      * flight. A fill grows the source rectangle out to the pointer; a move
@@ -368,8 +478,13 @@ export function createSelection(ctx) {
             ? { rowIndex: active.rowIndex, colIndex: active.colIndex }
             : null;
         if (event.shiftKey) {
+            // The range grows to the clicked cell and the active cell stays where
+            // it is, as in Excel: it is the cell the formula bar shows and the
+            // one the next keystroke edits. Used to jump to the clicked corner,
+            // so a Shift+click to select B2:D5 then typing wrote into D5.
             extendSelection(rowIndex, colIndex);
-            setActiveCell(rowIndex, colIndex);
+            if (!active)
+                setActiveCell(rowIndex, colIndex);
         }
         else {
             setActiveCell(rowIndex, colIndex);
@@ -390,8 +505,9 @@ export function createSelection(ctx) {
         const row = ctx.allRows[rowIndex];
         if (!row || isGroupRow(row))
             return;
+        // The active cell is where the drag began; only the range's far corner
+        // follows the pointer.
         extendSelection(rowIndex, colIndex);
-        setActiveCell(rowIndex, colIndex);
     }
     /** `event` is the window `pointerup` when this comes from the real gesture,
      *  and absent when `onWindowPointerMove` calls it to recover from a release
@@ -516,11 +632,12 @@ export function createSelection(ctx) {
             return;
         }
         // onCellPointerDown already set active+selection for data cells. Only
-        // decide whether to enter edit mode (click on the previously-active cell).
+        // decide whether to enter edit mode (click on the previously-active cell,
+        // unless the grid was told a second click is just a click).
         const wasActive = ctx.activeAtPointerDown !== null &&
             ctx.activeAtPointerDown.rowIndex === rowIndex &&
             ctx.activeAtPointerDown.colIndex === colIndex;
-        if (wasActive && ctx.editingEnabled) {
+        if (wasActive && ctx.editingEnabled && ctx.props.editOnSecondClick !== false) {
             ctx.onCellDoubleClick(rowIndex, colIndex);
             return;
         }
@@ -556,12 +673,15 @@ export function createSelection(ctx) {
         isRowSelected,
         toggleRowSelectionById,
         toggleSelectAllRows,
+        setSelectAllRows,
         setActiveCell,
         scrollActiveCellIntoView,
         setSelection,
         extendSelection,
         isCellInSelectedRange,
         getCellRangeEdges,
+        activeRangeRect,
+        cellSelectionState,
         fillMarqueeEdges,
         getSelectionRects,
         isInFillPreview,

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

@@ -0,0 +1,214 @@
+/**
+ * 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".
+ *
+ * A symbol, for two reasons. It cannot collide with a field in anyone's row
+ * data, which a string key like `__svPlaceholder` eventually would. And
+ * `Symbol.for` puts it in the global registry, so a placeholder still reads as
+ * one after it has crossed a module boundary - two copies of this file loaded
+ * through different specifiers would otherwise mint different symbols.
+ */
+declare const PLACEHOLDER: unique symbol;
+/** Rows the cache has not loaded. One shared object per state, not per row. */
+declare const LOADING_ROW: Readonly<{
+    [PLACEHOLDER]: "loading";
+}>;
+declare const FAILED_ROW: Readonly<{
+    [PLACEHOLDER]: "failed";
+}>;
+/**
+ * Why a row is not real data, or `null` when it is.
+ *
+ * Deliberately NOT an identity check. The sentinels are shared objects, so
+ * `row === LOADING_ROW` looks like the obvious test - but rows routinely
+ * arrive here through something that wrapped them. Svelte is the everyday
+ * case: assigning the controller state into `$state` makes the row array
+ * deeply reactive, and every row read back out is a proxy of the original.
+ * Identity fails, every placeholder reads as real data, and the grid renders
+ * a screen of blank rows instead of skeletons. Reading the mark works through
+ * any wrapper that forwards property access, which is all of them.
+ */
+export declare function rowPlaceholderState(row: unknown): 'loading' | 'failed' | null;
+/**
+ * Mint a frozen placeholder the grid will recognise, carrying whatever
+ * other fields the caller wants on it. The row model uses this to give its
+ * placeholders a `kind`, so code reading display rows and code reading grid
+ * rows agree on what they are looking at.
+ */
+export declare function createRowPlaceholder<T extends object>(state: 'loading' | 'failed', fields: T): Readonly<T & {
+    readonly [PLACEHOLDER]: 'loading' | 'failed';
+}>;
+/** What a block fetch has to answer with. `rowCount` is optional: see {@link BlockCacheOptions}. */
+export type BlockFetchResult<TData> = {
+    rows: ReadonlyArray<TData>;
+    /**
+     * Total rows after filtering. Omit it (or send `-1`) when the backend cannot
+     * count cheaply - the cache then discovers the end from the first short
+     * block, and `lastRowKnown()` stays false until it does.
+     */
+    rowCount?: number;
+};
+/** What a block cache is built from: block size, caps, debounce and the fetch. */
+export type BlockCacheOptions<TData> = {
+    /**
+     * Rows per request. Bigger blocks mean fewer round trips and more wasted
+     * rows when the user scrolls past; 100 is the usual compromise.
+     */
+    blockSize?: number;
+    /**
+     * Keep at most this many loaded blocks. Blocks outside the viewport are
+     * evicted least-recently-seen first, and scrolling back re-fetches them.
+     * Unlimited by default, which is right until the dataset is big enough that
+     * holding every visited block matters.
+     */
+    maxBlocksInCache?: number;
+    /** Requests open at once. Default 2. */
+    maxConcurrentRequests?: number;
+    /**
+     * Wait this long after the viewport settles before fetching. Non-zero values
+     * stop a drag of the scrollbar from requesting every block it flies past.
+     */
+    blockLoadDebounceMs?: number;
+    /**
+     * Rows to claim before anything is loaded, so the grid has a scrollbar (and
+     * `scrollToRow` has somewhere to land) on the first paint. Default 1.
+     */
+    initialRowCount?: number;
+    /**
+     * While the total is unknown, how many unloaded rows to keep past the last
+     * loaded one. Scrolling into them is what asks for the next block. Default 1.
+     */
+    overflowRows?: number;
+    /** Fetch one block. Reject, or throw, to mark it failed. */
+    fetch: (startRow: number, endRow: number, signal: AbortSignal) => Promise<BlockFetchResult<TData>>;
+    /** Called after any change to the rows, the count, or a block's state. */
+    onChange: (cache: BlockCacheState) => void;
+    /**
+     * How to coalesce `onChange`. Defaults to a microtask, so a burst of block
+     * arrivals rebuilds the row array once. Pass `(fn) => fn()` in tests to make
+     * every change synchronous.
+     */
+    schedule?: (flush: () => void) => void;
+};
+/** One block's place in the world, for diagnostics and for tests. */
+export type BlockState = {
+    blockIndex: number;
+    startRow: number;
+    endRow: number;
+    status: 'loading' | 'loaded' | 'failed';
+    /** Monotonic counter of when the viewport last covered this block. */
+    lastTouched: number;
+};
+/** One block as `getCacheState()` reports it. */
+export type BlockCacheState = {
+    /** Rows after filtering, or `null` while the backend has not said. */
+    rowCount: number | null;
+    /** False while the end of the data is still being discovered. */
+    lastRowKnown: boolean;
+    /** True while at least one block is in flight. */
+    loading: boolean;
+    /** Blocks whose fetch rejected. Empty unless something went wrong. */
+    failedBlocks: number[];
+};
+/**
+ * A block cache: rows arrive in blocks as the viewport reaches them,
+ * placeholders stand in until then, and blocks far from the viewport are
+ * evicted past the cap.
+ */
+export type BlockCache<TData> = {
+    /**
+     * Tell the cache which rows are on screen. Fetches what is missing (after
+     * `blockLoadDebounceMs`) and marks those blocks as recently seen so eviction
+     * spares them. Safe to call on every scroll frame.
+     */
+    setViewport(startIndex: number, endIndex: number): void;
+    /** The dense row array to hand the grid. Placeholders fill unloaded slots. */
+    rows(): 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;
+    lastRowKnown(): boolean;
+    /** Re-fetch the blocks that failed. */
+    retryFailed(): void;
+    /**
+     * Re-fetch the loaded blocks in place, keeping the row count and scroll
+     * position. What you want after a mutation lands on the server.
+     */
+    refresh(): void;
+    /** Drop everything and start over from the current viewport. */
+    purge(): void;
+    /** Override the total, e.g. from a count endpoint that answered separately. */
+    setRowCount(count: number | null, known?: boolean): void;
+    /**
+     * Write rows straight into the cache from `startRow`, as if a fetch had
+     * returned them, bypassing the datasource, the debounce and the
+     * concurrency cap. `startRow` must sit on a block boundary. An explicit
+     * `rowCount` settles the total; without one a short final slice does.
+     */
+    applyRows(startRow: number, rows: ReadonlyArray<TData>, rowCount?: number): void;
+    /** Replace one loaded row. No-op when its block is not loaded. */
+    patch(index: number, row: TData): boolean;
+    /**
+     * The index of the first LOADED row matching `predicate`, or -1. Rows
+     * that are not loaded are not visited - a transaction addressed by id
+     * can only touch what is in the cache.
+     */
+    findIndex(predicate: (row: TData, index: number) => boolean): number;
+    /**
+     * Insert rows at an index and grow the count. Works within whichever
+     * run of loaded blocks contains `index`; loaded blocks AFTER that run
+     * are dropped, because their rows have shifted and will be re-fetched at
+     * their new offsets. An index in an unloaded region grows the count
+     * only (the rows exist; they arrive when scrolled to). Returns whether
+     * the rows were placed in the cache.
+     */
+    insert(index: number, rows: ReadonlyArray<TData>): boolean;
+    /**
+     * Remove `count` rows at an index and shrink the count, with the same
+     * run semantics as `insert`. Returns how many rows were actually
+     * removed from the cache.
+     */
+    remove(index: number, count?: number): number;
+    /** Every block the cache is holding, for `debug` output and tests. */
+    getCacheState(): BlockState[];
+    /** Abort what is in flight and stop emitting. Call on unmount. */
+    dispose(): void;
+};
+/**
+ * Build a block cache over a `fetch(startRow, endRow, signal)`. The free
+ * infinite row model and the Enterprise server-side row model both run on
+ * it, one per level.
+ */
+export declare function createBlockCache<TData>(options: BlockCacheOptions<TData>): BlockCache<TData>;
+export {};