@svgrid/grid 3.0.2 → 3.0.4

package/dist/shortcut-registry.d.ts

@@ -0,0 +1,145 @@
+/**
+ * shortcut-registry - the injection seam for keyboard commands the free grid
+ * does not implement. `@svgrid/grid` owns cell navigation, copy/paste, undo and
+ * find; the Excel command set (Ctrl+Arrow to the edge of a data region, Ctrl+D
+ * fill down, Ctrl+Shift+V paste special, Alt+= autosum) is a paid feature in
+ * `@svgrid/enterprise`. This holder lets enterprise register a handler at
+ * import time; the grid runs the chain before it interprets a key itself.
+ *
+ * Same shape as `selection-bar-view`, `scheduler-view` and `board-view`, with
+ * one difference: those hold a single renderer, this holds a prioritised chain,
+ * because several packages may want a key and the first claim has to win
+ * deterministically.
+ *
+ * The chain runs BEFORE `getKeyboardIntent`, which is the whole point. The
+ * intent union in `keyboard.ts` is public API and closed, so there is no member
+ * that could mean "jump to the edge of the data region" and no way to add one
+ * without breaking a consumer that switches on it exhaustively. Running first
+ * sidesteps that: a registered handler claims `Ctrl+ArrowDown` and returns
+ * true, and the grid never computes an intent for that event at all.
+ *
+ * ```ts
+ * // in @svgrid/enterprise, at module load:
+ * import { registerGridShortcuts } from '@svgrid/grid'
+ * registerGridShortcuts(handleSheetKey, { id: 'sheet', priority: 100 })
+ * ```
+ */
+import type { SvGridApi } from './index.js';
+/** What a handler gets to read and write. A getter object over controller
+ *  state, built only when at least one handler is registered - a free grid
+ *  never pays to construct it. Indices are DISPLAY indices, matching
+ *  `SelectionPoint`, so they follow sort, filter and pagination. */
+export type GridCommandContext = {
+    /** The grid's public api. Identity is stable for the life of the grid, so
+     *  a handler can key per-grid state on it in a WeakMap. */
+    readonly api: SvGridApi<any, any>;
+    /** True when the event came from the cell editor rather than the grid root.
+     *  Handlers that only make sense mid-edit (Alt+Enter) check this. */
+    readonly editing: boolean;
+    /**
+     * The open inline editor's element, or null. A binding registered for
+     * `editing: true` reads and rewrites the text through it: F4 in a
+     * spreadsheet pins the reference under the caret.
+     */
+    readonly editor: HTMLInputElement | HTMLTextAreaElement | null;
+    readonly activeCell: {
+        rowIndex: number;
+        colIndex: number;
+        columnId: string | null;
+    } | null;
+    /**
+     * The corner the active range grows from: the far end of a Shift+Arrow,
+     * Shift+click or drag, which need not be the active cell. Null while
+     * nothing is anchored. A command that extends the selection steps from
+     * here, not from the active cell, or Ctrl+Shift+Down twice would land
+     * on the same edge twice.
+     */
+    readonly selectionFocus: {
+        rowIndex: number;
+        colIndex: number;
+    } | null;
+    readonly rowCount: number;
+    readonly colCount: number;
+    /** Every selected rectangle as [minRow, minCol, maxRow, maxCol], active last. */
+    readonly ranges: ReadonlyArray<readonly [number, number, number, number]>;
+    columnIdAt(colIndex: number): string | null;
+    getCellValue(rowIndex: number, colIndex: number): unknown;
+    /** Write a cell and record it in the grid's undo history. Inside `batch`
+     *  every write joins one step, so a fill or a replace-all is one Ctrl+Z. */
+    setCellValue(rowIndex: number, colIndex: number, value: unknown): void;
+    setActiveCell(rowIndex: number, colIndex: number): void;
+    setSelection(rowIndex: number, colIndex: number): void;
+    extendSelection(rowIndex: number, colIndex: number): void;
+    scrollIntoView(rowIndex: number, colIndex: number): void;
+    startEditing(rowIndex: number, colIndex: number, seed?: string): boolean;
+    /** Run every write inside `fn` as ONE undo step. Returns what `fn` returns. */
+    batch<T>(fn: () => T): T;
+    /**
+     * Put something that is not a cell write into the grid's undo history:
+     * a format kept in the caller's own store, a structural change the grid
+     * cannot see. `undo` and `redo` are what Ctrl+Z and Ctrl+Y will call.
+     * Inside `batch` the step joins the batch, so a command that writes cells
+     * AND formats is still one press.
+     */
+    recordUndo(undo: () => void, redo: () => void): void;
+    /**
+     * Put keyboard focus back on the grid, without scrolling.
+     *
+     * A toolbar button takes focus when it is clicked and a dialog takes it
+     * when it opens, so the keystroke after either - Ctrl+Z to undo what the
+     * button did, typing into the cell the dialog changed - lands on the button
+     * or on `<body>` rather than on the grid. Excel returns focus to the sheet
+     * after every ribbon command and every dialog; a command that owns chrome
+     * calls this once it is done.
+     */
+    focus(): void;
+    /**
+     * Paste the system clipboard at the active cell, the way Ctrl+V does:
+     * tab-separated text becomes a block of cells, one undo step. Resolves
+     * once the paste has been applied, or without doing anything when the
+     * clipboard cannot be read (an insecure context, or permission refused),
+     * which is the same silence Ctrl+V keeps there.
+     */
+    paste(): Promise<void>;
+    /**
+     * Copy the selection the way Ctrl+C does: every selected rectangle as
+     * tab-separated text, each cell through `processCellForClipboard`. The
+     * api's `copyToClipboard` is the export: the displayed rows with their
+     * headers, whatever the selection.
+     */
+    copy(): void;
+    /**
+     * Cut the selection the way Ctrl+X does: the copy above, then the cells
+     * cleared as one undo step.
+     */
+    cut(): Promise<void>;
+    /**
+     * Whether a cell may be written: the column's `editable` predicate as
+     * the grid's own editor, fill handle and paste read it. `setCellValue`
+     * does not consult it (a command is trusted to know what it writes), so
+     * a command that fills or stamps a range asks here and skips the cells
+     * that say no. Optional for a context built by hand.
+     */
+    canEdit?(rowIndex: number, colIndex: number): boolean;
+};
+/** Return true to consume the event. The grid stops there and does not
+ *  interpret the key itself. Return false to let it fall through. */
+export type GridShortcutHandler = (event: KeyboardEvent, cmd: GridCommandContext) => boolean;
+/**
+ * Register a keyboard handler. Higher `priority` runs first; ties keep
+ * registration order. Passing an `id` that is already registered replaces that
+ * entry rather than stacking a second copy, so an enable* function stays
+ * idempotent. Returns an unregister function.
+ */
+export declare function registerGridShortcuts(handler: GridShortcutHandler, opts?: {
+    id?: string;
+    priority?: number;
+}): () => void;
+/** Run the chain. Returns true when a handler consumed the event. */
+export declare function runGridShortcuts(event: KeyboardEvent, cmd: GridCommandContext): boolean;
+/** Whether anything is registered. The grid checks this before building a
+ *  command context, so an unregistered grid pays one array-length read. */
+export declare function hasGridShortcuts(): boolean;
+/** Drop every handler. Tests use this; production code should keep the
+ *  unregister function `registerGridShortcuts` returns. */
+export declare function clearGridShortcuts(): void;

package/dist/shortcut-registry.js

@@ -0,0 +1,44 @@
+// Module-level, not $state: the chain is written at import time by whoever
+// installs a feature pack and read inside an event handler. Nothing renders
+// from it, so reactivity would cost a proxy for no benefit.
+let entries = [];
+/**
+ * Register a keyboard handler. Higher `priority` runs first; ties keep
+ * registration order. Passing an `id` that is already registered replaces that
+ * entry rather than stacking a second copy, so an enable* function stays
+ * idempotent. Returns an unregister function.
+ */
+export function registerGridShortcuts(handler, opts) {
+    const entry = {
+        handler,
+        id: opts?.id,
+        priority: opts?.priority ?? 0,
+    };
+    const next = entry.id ? entries.filter((e) => e.id !== entry.id) : entries.slice();
+    next.push(entry);
+    // Stable sort by descending priority: Array.prototype.sort is stable per
+    // spec, so equal priorities keep the order they were pushed in.
+    next.sort((a, b) => b.priority - a.priority);
+    entries = next;
+    return () => {
+        entries = entries.filter((e) => e !== entry);
+    };
+}
+/** Run the chain. Returns true when a handler consumed the event. */
+export function runGridShortcuts(event, cmd) {
+    for (const entry of entries) {
+        if (entry.handler(event, cmd))
+            return true;
+    }
+    return false;
+}
+/** Whether anything is registered. The grid checks this before building a
+ *  command context, so an unregistered grid pays one array-length read. */
+export function hasGridShortcuts() {
+    return entries.length > 0;
+}
+/** Drop every handler. Tests use this; production code should keep the
+ *  unregister function `registerGridShortcuts` returns. */
+export function clearGridShortcuts() {
+    entries = [];
+}

package/dist/svgrid-wrapper.types.d.ts

@@ -1,8 +1,9 @@
 import type { CellFormatConfig, ColumnDef, RowData, SvGridOptions, TableFeatures } from './core.js';
 import type { FilterOperator, Props } from './SvGrid.types.js';
 import type { GridExportOptions, GridClipboardOptions } from './export-format.js';
-import type { ChartSpec, ChartType } from './chart.js';
+import type { ChartFormatState, ChartReducer, ChartSpec, ChartTimeBucket, ChartType, ChartZoomWindow } from './chart.js';
 import type { GridPredicateExpr } from './filtering/predicate-expr.js';
+import type { GridCommandContext } from './shortcut-registry.js';
 /** The comparisons a column filter can use, as shown in the filter menu. */
 export type SvGridFilterOperator = FilterOperator;
 /**
@@ -56,21 +57,78 @@ export type SvGridViewState = {
         reduce: 'sum' | 'avg' | 'count';
         stacked: boolean;
     };
-    /** All charts in the tab strip (multi-chart), plus the active index. */
-    charts?: Array<{
-        title: string;
-        type: ChartType;
-        dimension: string | null;
-        series: string | null;
-        measure: string | null;
-        reduce: 'sum' | 'avg' | 'count';
-        stacked: boolean | null;
-        dataLabels: boolean | null;
-        logScale: boolean | null;
-        timeAxis: boolean | null;
-        valueFormat: 'number' | 'currency' | 'percent' | 'compact' | null;
-    }>;
+    /** All charts in the tab strip (multi-chart), plus the active index.
+     *  Every field the panel can change is here so a saved view restores the
+     *  chart exactly; `null` inherits the `charting` config. */
+    charts?: ChartTabSnapshot[];
     chartActive?: number;
+    /** The named charts kept with `api.saveChart`; present only when there is one. */
+    savedCharts?: SavedChart[];
+};
+/** One chart tab as the saved view carries it (`GridState.charts[i]`). */
+export type ChartTabSnapshot = {
+    title: string;
+    type: ChartType;
+    dimension: string | null;
+    series: string | null;
+    measure: string | null;
+    /** Scatter's y measure, a range's high, a bullet's target. */
+    measure2?: string | null;
+    reduce: ChartReducer;
+    stacked: boolean | null;
+    stacked100?: boolean | null;
+    orientation?: 'vertical' | 'horizontal' | null;
+    donut?: boolean | null;
+    palette?: string[] | null;
+    dataLabels: boolean | null;
+    logScale: boolean | null;
+    timeAxis: boolean | null;
+    valueFormat: 'number' | 'currency' | 'percent' | 'compact' | null;
+    bucket?: ChartTimeBucket | null;
+    bins?: number | null;
+    funnelShape?: 'trapezoid' | 'pyramid' | 'cone' | null;
+    candleStyle?: 'classic' | 'hollow' | 'heikin-ashi' | null;
+    /** The zoom window as category indices, or null for the whole chart. */
+    zoom?: ChartZoomWindow | null;
+    ohlc?: {
+        open: string | null;
+        high: string | null;
+        low: string | null;
+        close: string | null;
+        volume: string | null;
+    } | null;
+    indicators?: string[];
+    format?: ChartFormatState | null;
+    /** An unlinked chart carries the spec it was frozen with. */
+    frozen?: {
+        spec: ChartSpec;
+        at: string;
+    } | null;
+};
+/** A chart configuration kept under a name (`api.saveChart`). */
+export type SavedChart = {
+    name: string;
+    /** ISO timestamp of the save. */
+    savedAt: string;
+    /** The tab's state at the time; `applySavedChart` puts it on the active tab. */
+    tab: ChartTabSnapshot;
+};
+/** One cell, in the 0-based display coordinates every selection method uses. */
+export type SvGridCellCoords = {
+    row: number;
+    col: number;
+};
+/**
+ * A selected rectangle with its orientation kept: `from` is where the
+ * selection was started (the anchor) and `to` where it ended (the focus),
+ * so a range dragged upwards has `from.row > to.row`. `highlight` is the
+ * active cell inside it. The same three fields as Handsontable's CellRange,
+ * so code written against `getSelectedRange()` there reads the same here.
+ */
+export type SvGridSelectedRange = {
+    from: SvGridCellCoords;
+    to: SvGridCellCoords;
+    highlight: SvGridCellCoords;
 };
 /**
  * A batch of row mutations for `api.applyTransaction`. `update` / `remove`
@@ -112,17 +170,44 @@ export type SvGridApi<TFeatures extends TableFeatures, TData extends RowData> =
      * range is `[rowStart, colStart, rowEnd, colEnd]` in 0-indexed grid
      * coordinates. Pass an empty array to clear the selection.
      *
-     * The grid currently honours the FIRST range only (single-range
-     * engine); subsequent ranges are accepted for API forward compat
-     * but ignored. The grid's active cell jumps to the range's start
-     * corner.
+     * Every range is honoured: the last one becomes the active range and
+     * the others stay highlighted beside it, as after a Ctrl+drag. The
+     * active cell goes to the last range's start corner.
      */
     selectCells(ranges: ReadonlyArray<readonly [number, number, number, number]>): void;
     /**
-     * Returns the current cell-selection rectangles in the same shape
-     * `selectCells` accepts. Empty array when no range is active.
+     * The current cell-selection rectangles in the same shape `selectCells`
+     * accepts, each normalised to `[minRow, minCol, maxRow, maxCol]`, in the
+     * order they were selected with the active one last. Empty array when no
+     * range is active.
+     *
+     * Handsontable's method of the same name. Two differences, both on
+     * purpose: an empty array rather than `undefined`, so `getSelected()[0]`
+     * never throws; and normalised corners, so a loop from the first row to
+     * the last cannot run zero times because the range was dragged upwards.
+     * For the orientation, and the active cell inside a range, use
+     * `getSelectedRange()`.
+     *
+     * With cell selection off (`selectable={false}`) no rectangle is ever
+     * recorded and this stays `[]`; the focused cell is `getActiveCell()`.
      */
     getSelected(): Array<[number, number, number, number]>;
+    /**
+     * The most recently selected rectangle as `[startRow, startCol, endRow,
+     * endCol]`, start being where the selection began, or `undefined` when
+     * nothing is selected. Handsontable's `getSelectedLast()`, orientation
+     * included: a range dragged upwards has `startRow > endRow`.
+     */
+    getSelectedLast(): [number, number, number, number] | undefined;
+    /**
+     * Every selected rectangle with its orientation and active cell, oldest
+     * first, or `undefined` when nothing is selected. Handsontable's
+     * `getSelectedRange()`.
+     */
+    getSelectedRange(): SvGridSelectedRange[] | undefined;
+    /** The most recently selected rectangle, or `undefined`. Handsontable's
+     *  `getSelectedRangeLast()`. */
+    getSelectedRangeLast(): SvGridSelectedRange | undefined;
     /** Open the built-in chart panel. */
     openChart(): void;
     /** Close the built-in chart panel. */
@@ -141,19 +226,69 @@ export type SvGridApi<TFeatures extends TableFeatures, TData extends RowData> =
         dimension?: string | null;
         series?: string | null;
         measure?: string | null;
-        reduce?: 'sum' | 'avg' | 'count';
+        reduce?: ChartReducer;
         stacked?: boolean;
         dataLabels?: boolean;
         logScale?: boolean;
         timeAxis?: boolean;
         valueFormat?: 'number' | 'currency' | 'percent' | 'compact';
+        /** Group a date dimension by calendar unit; `null` returns to exact values. */
+        bucket?: ChartTimeBucket | null;
+        /** Second measure: a scatter's Y, a range's high end, a bullet's target. */
+        measure2?: string | null;
+        /** Histogram bin count; `null` for Sturges' rule. */
+        bins?: number | null;
+        funnelShape?: 'trapezoid' | 'pyramid' | 'cone' | null;
+        candleStyle?: 'classic' | 'hollow' | 'heikin-ashi' | null;
+        /** Candlestick / OHLC: the price columns (ids or fields); `null` goes
+         *  back to guessing them from the column names. */
+        ohlc?: {
+            open?: string | null;
+            high?: string | null;
+            low?: string | null;
+            close?: string | null;
+            volume?: string | null;
+        } | null;
+        /** Indicator panes under a price chart (`volume`, `rsi`, `macd`,
+         *  `stochastic`, `atr`, `obv`) and overlays on it (`sma`, `ema`,
+         *  `bb`, `vwap`). */
+        indicators?: Array<'volume' | 'rsi' | 'macd' | 'stochastic' | 'atr' | 'obv' | 'sma' | 'ema' | 'bb' | 'vwap'>;
+        /** The builder's format state (titles, axes, legend, per-series style);
+         *  `null` resets it. */
+        format?: ChartFormatState | null;
+        /** `true` unlinks the chart from the grid (it keeps the spec it has),
+         *  `false` links it back. */
+        frozen?: boolean;
+        /** Apply a saved chart (by name) to the active tab before the other keys. */
+        saved?: string;
     }): void;
+    /**
+     * Keep the active chart's whole configuration (type, columns, aggregate,
+     * switches, indicators, format, zoom) under a name. A same-named entry is
+     * replaced. Saved charts travel with `getState()` / `setState()` and show
+     * in the panel's Saved charts popover.
+     */
+    saveChart(name: string): void;
+    /** Apply a saved chart to the active tab, which keeps its title. `false` when no chart has that name. */
+    applySavedChart(name: string): boolean;
+    removeSavedChart(name: string): void;
+    getSavedCharts(): SavedChart[];
     /**
      * Register a natural-language "chart this" handler. When set, the chart
      * panel shows an AI button. `@svgrid/enterprise`'s `enableAiCharting(api)`
      * fills this. Pass `null` to remove it.
      */
     setChartAiHandler(handler: ((prompt: string) => Promise<Record<string, unknown> | null>) | null): void;
+    /**
+     * Register an "explain this chart" handler. When set, the chart panel's AI
+     * row shows an Explain button that reads the active chart and shows the
+     * summary and insights it returns. `enableAiCharting(api)` fills this with
+     * `aiExplainChart`. Pass `null` to remove it.
+     */
+    setChartExplainHandler(handler: (() => Promise<{
+        summary: string;
+        insights: string[];
+    } | null>) | null): void;
     /** Add one row. `position` defaults to `'bottom'`. */
     addRow(row: TData, position?: 'top' | 'bottom' | number): void;
     addRows(rows: ReadonlyArray<TData>, position?: 'top' | 'bottom' | number): void;
@@ -227,6 +362,13 @@ export type SvGridApi<TFeatures extends TableFeatures, TData extends RowData> =
      * `editorOptions` returns a Promise - static lists are never refetched.
      */
     refreshEditorOptions(columnId?: string): void;
+    /**
+     * Open the `contextMenu` at the pointer, for the cell at (rowIndex,
+     * colIndex), from an element of your own: a spreadsheet's column letters
+     * and row numbers offer the cell menu for the column or row they select.
+     * Does nothing without a `contextMenu` prop.
+     */
+    openContextMenu(event: MouseEvent, rowIndex: number, colIndex: number): void;
     /**
      * Clear every active column filter (menu, filter-row, set-list, global, and
      * the advanced filter). Resets the grid to "no filtering" in a single call.
@@ -331,6 +473,43 @@ export type SvGridApi<TFeatures extends TableFeatures, TData extends RowData> =
      * "Autosize" item.
      */
     autosizeColumn(columnId: string): void;
+    /**
+     * The height of a row in px: the one it was dragged or set to, else the
+     * declared `rowHeight` (30 when none). `rowIndex` is a display index.
+     */
+    getRowHeight(rowIndex: number): number;
+    /**
+     * Give a row its own height, the way dragging its grip does with
+     * `rowResize`; `null` takes it back to the declared height. The height
+     * belongs to the row (its id), so it follows the row through a sort and
+     * survives the data being replaced. Ignored under `autoRowHeight`, where
+     * the content decides.
+     */
+    setRowHeight(rowIndex: number, height: number | null): void;
+    /**
+     * Fold a column to nothing, the way a spreadsheet hides one: it keeps
+     * its index, its cells and its width, and takes no room until it is
+     * unfolded. Unlike `setColumnVisible(id, false)`, which takes the
+     * column out of the model and shifts every index after it, references
+     * by index stay valid, so a sheet's formulas and formats are untouched.
+     * Arrow keys, Tab and Enter step over a collapsed column.
+     */
+    setColumnCollapsed(columnId: string, collapsed: boolean): void;
+    isColumnCollapsed(columnId: string): boolean;
+    /**
+     * Fold a row to nothing, the row-side twin of `setColumnCollapsed`.
+     * `rowIndex` is a display index; the fold belongs to the row (its id)
+     * and follows it through a sort.
+     */
+    setRowCollapsed(rowIndex: number, collapsed: boolean): void;
+    isRowCollapsed(rowIndex: number): boolean;
+    /** The `mergedCells` in force, copied: origins with their spans. */
+    getMergedCells(): Array<{
+        rowIndex: number;
+        colIndex: number;
+        rowSpan: number;
+        colSpan: number;
+    }>;
     /** Run `autosizeColumn` on every column. */
     autosizeAllColumns(): void;
     /**
@@ -381,6 +560,18 @@ export type SvGridApi<TFeatures extends TableFeatures, TData extends RowData> =
     canRedo(): boolean;
     /** Wipe both stacks (e.g. after a server save commits the buffer). */
     clearHistory(): void;
+    /**
+     * The same `GridCommandContext` a registered shortcut handler receives.
+     *
+     * Keyboard commands are handed one on every keystroke, but a button in a
+     * ribbon or a toolbar has no keystroke to ride in on, and re-implementing
+     * "bold the selection" against the api would give the button and the key
+     * two code paths that drift. Both go through this instead.
+     *
+     * Live, not a snapshot: the object reads through to the grid, so one built
+     * once at mount still reports the current selection.
+     */
+    getCommandContext(): GridCommandContext;
     /** Open the built-in find overlay (Ctrl+F also opens it). */
     openFind(): void;
     /** Close the find overlay and clear the query. */

package/dist/virtualization/virtualizer.js

@@ -23,25 +23,41 @@ function sameState(a, b) {
     for (let i = 0; i < a.items.length; i += 1) {
         const ai = a.items[i];
         const bi = b.items[i];
-        if (ai.index !== bi.index || ai.start !== bi.start || ai.size !== bi.size)
+        if (ai.index !== bi.index || ai.start !== bi.start || ai.size !== bi.size || ai.key !== bi.key)
             return false;
     }
     return true;
 }
-// Slot-based keying: the key is the POSITION of the item inside the
-// visible window (slot 0 = topmost rendered row, slot 1 = next, etc.)
-// - NOT the data index. As the user scrolls, the window's startIndex
-// changes but the slot keys stay the same (0..N-1), so Svelte recycles
-// the existing <tr> DOM nodes and only updates their data + position.
+// Slot-based keying: the key is a SLOT number, not the data index, so the
+// same N <tr> nodes stay alive for the lifetime of the grid and scrolling
+// never mounts or unmounts a row. With data-index keys, scrolling down one
+// row meant the old topmost key disappeared and a new bottommost key
+// appeared, so Svelte unmounted the top <tr> and mounted a fresh one at the
+// bottom on every scroll tick.
 //
-// This avoids the mount/unmount churn that previously fired on every
-// scroll tick: with data-index keys, scrolling down 1 row meant the old
-// topmost key disappeared and a new bottommost key appeared, forcing
-// Svelte to unmount the top <tr> and mount a fresh one at the bottom.
-// Slot-based keys keep the same N <tr> nodes alive for the lifetime of
-// the grid; scroll just translates them via the top spacer.
+// The slot for data index i is `i mod N`, N being the window length. That
+// matters for what a one-row scroll costs: while N holds, a row that stays
+// inside the window keeps its slot, so Svelte keeps its <tr> and touches
+// nothing in it, and only the row that entered gets new content - the keyed
+// each moves that one <tr> to the other end with a single `insertBefore`.
+// The earlier `i - startIndex` slot scheme handed EVERY rendered row a new
+// index on every one-row scroll, so an arrow key re-rendered all ~30 rows x
+// every rendered column to shift the data up by one.
+//
+// The modulus has to be EXACTLY N, not merely >= N: under a larger modulus
+// the window's residues are a proper subset, so each one-row scroll drops
+// one residue and picks up another, and Svelte unmounts a <tr> and mounts a
+// fresh one instead of moving it (measured: mount + unmount per arrow key,
+// zero moves). When N changes - the top and bottom overscan clamping on the
+// first and last rows, a resize, variable row heights - every slot remaps
+// and the whole window re-renders once, which is what the old scheme did on
+// every tick.
+function slotKey(index, windowLength) {
+    return `virtual_slot_${index % windowLength}`;
+}
 function buildUniformItems(startIndex, endIndex, estimateSize) {
     const items = [];
+    const windowLength = endIndex - startIndex + 1;
     for (let index = startIndex; index <= endIndex; index += 1) {
         const start = index * estimateSize;
         items.push({
@@ -49,7 +65,7 @@ function buildUniformItems(startIndex, endIndex, estimateSize) {
             start,
             size: estimateSize,
             end: start + estimateSize,
-            key: `virtual_slot_${index - startIndex}`,
+            key: slotKey(index, windowLength),
         });
     }
     return items;
@@ -72,11 +88,12 @@ export function buildPreMeasureItems(count, estimateSize, viewportHeight, oversc
         return [];
     const size = Math.max(estimateSize, 1);
     const visible = Math.ceil(Math.max(viewportHeight, 0) / size);
-    const endIndex = Math.min(visible + Math.max(overscan, 0), count - 1);
-    return buildUniformItems(0, Math.max(endIndex, 0), size);
+    const endIndex = Math.max(Math.min(visible + Math.max(overscan, 0), count - 1), 0);
+    return buildUniformItems(0, endIndex, size);
 }
 function buildVariableItems(startIndex, endIndex, offsets) {
     const items = [];
+    const windowLength = endIndex - startIndex + 1;
     for (let index = startIndex; index <= endIndex; index += 1) {
         const start = offsets[index] ?? 0;
         const end = offsets[index + 1] ?? start;
@@ -85,7 +102,7 @@ function buildVariableItems(startIndex, endIndex, offsets) {
             start,
             size: end - start,
             end,
-            key: `virtual_slot_${index - startIndex}`,
+            key: slotKey(index, windowLength),
         });
     }
     return items;
@@ -168,8 +185,12 @@ export function createVirtualizer(initial) {
         const sizeFn = options.estimateSize;
         const offsets = new Array(count + 1);
         offsets[0] = 0;
+        // A size of 0 is a real size: a collapsed row or column takes no room
+        // and both searches below stay monotonic over equal offsets. Only a
+        // negative size is nonsense. The floor used to be 1, which left every
+        // hidden column a one-pixel sliver.
         for (let i = 0; i < count; i += 1) {
-            offsets[i + 1] = offsets[i] + Math.max(sizeFn(i), 1);
+            offsets[i + 1] = offsets[i] + Math.max(sizeFn(i), 0);
         }
         offsetCache = { fn: sizeFn, count, offsets };
         return offsets;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svgrid/grid",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "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",
@@ -94,6 +94,11 @@
       "svelte": "./dist/filtering/excel-filters.js",
       "import": "./dist/filtering/excel-filters.js"
     },
+    "./shortcuts": {
+      "types": "./dist/shortcut-registry.d.ts",
+      "svelte": "./dist/shortcut-registry.js",
+      "import": "./dist/shortcut-registry.js"
+    },
     "./flex-render": {
       "types": "./dist/flex-render.d.ts",
       "svelte": "./dist/flex-render.js",