@svgrid/grid 3.0.2 → 3.0.4

package/src/scroll-sync.test.ts

@@ -203,6 +203,47 @@ describe('scheduleScrollSync / flushScheduledScrollSync', () => {
   })
 })
 
+describe('syncScrollNow', () => {
+  let cancelled: number[] = []
+  beforeEach(() => {
+    cancelled = []
+    vi.stubGlobal('requestAnimationFrame', () => 42)
+    vi.stubGlobal('cancelAnimationFrame', (h: number) => {
+      cancelled.push(h)
+    })
+  })
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('flushes the virtualizers synchronously, without waiting for a frame', () => {
+    const { ctx, ss } = syncFor({
+      rowVirtualizationEnabled: true,
+      columnVirtualizationEnabled: true,
+      domToLogicalRowOffset: (n: number) => n * 2,
+    })
+    ss.syncScrollNow(30, 88)
+    expect(ctx.pendingScrollTop).toBe(30)
+    expect(ctx.pendingScrollLeft).toBe(88)
+    expect(ctx.scrollVersion).toBe(1)
+    expect(ctx.virtualizer.setScrollOffset).toHaveBeenCalledWith(60)
+    expect(ctx.columnVirtualizer.setHorizontalOffset).toHaveBeenCalledWith(88)
+    expect(ctx.scrollSyncRaf).toBeNull()
+    expect(cancelled).toEqual([])
+  })
+
+  it('cancels a frame that a scroll event already scheduled, so the position is not applied twice', () => {
+    const { ctx, ss } = syncFor({ rowVirtualizationEnabled: true })
+    ss.scheduleScrollSync(10, 0)
+    expect(ctx.scrollSyncRaf).toBe(42)
+    ss.syncScrollNow(64, 0)
+    expect(cancelled).toEqual([42])
+    expect(ctx.scrollSyncRaf).toBeNull()
+    expect(ctx.virtualizer.setScrollOffset).toHaveBeenCalledTimes(1)
+    expect(ctx.virtualizer.setScrollOffset).toHaveBeenCalledWith(64)
+  })
+})
+
 describe('onBodyScroll', () => {
   beforeEach(() => {
     // These tests assert what happens BEFORE the frame runs, so the stub just
@@ -321,7 +362,7 @@ describe('createScrollSync wiring', () => {
   it('exposes the documented handler surface', () => {
     const { ss } = syncFor()
     expect(Object.keys(ss).sort()).toEqual(
-      ['flushScheduledScrollSync', 'hideTooltip', 'onBodyScroll', 'scheduleScrollSync', 'showTooltipFor'],
+      ['flushScheduledScrollSync', 'hideTooltip', 'onBodyScroll', 'scheduleScrollSync', 'showTooltipFor', 'syncScrollNow'],
     )
   })
 })

package/src/scroll-sync.ts

@@ -66,6 +66,30 @@ export function createScrollSync<
     ctx.scrollSyncRaf = requestAnimationFrame(flushScheduledScrollSync);
   }
 
+  /**
+   * Sync the virtualizers to a scroll position NOW instead of on the next
+   * animation frame.
+   *
+   * For a scroll the grid made itself - keyboard navigation bringing the
+   * active cell into view - the position is already known, and going through
+   * the browser's `scroll` event and then the rAF above put the row-window
+   * update one frame behind the key press: the keydown's own flush painted
+   * the active cell on the OLD rows, and the rows only caught up on the next
+   * frame. Two painted frames per arrow key. Syncing inline folds the window
+   * update into the same flush as the active-cell change, so the key press
+   * paints once. The `scroll` event still fires afterwards and re-syncs to
+   * the same offset, which the virtualizers treat as a no-op.
+   */
+  function syncScrollNow(scrollTop: number, scrollLeft: number) {
+    if (ctx.scrollSyncRaf !== null) {
+      cancelAnimationFrame(ctx.scrollSyncRaf);
+      ctx.scrollSyncRaf = null;
+    }
+    ctx.pendingScrollTop = scrollTop;
+    ctx.pendingScrollLeft = scrollLeft;
+    flushScheduledScrollSync();
+  }
+
   function onBodyScroll(event: Event) {
     const container = event.currentTarget as HTMLDivElement | null;
     if (!container) return;
@@ -91,6 +115,7 @@ export function createScrollSync<
     hideTooltip,
     flushScheduledScrollSync,
     scheduleScrollSync,
+    syncScrollNow,
     onBodyScroll,
   };
 }

package/src/selection.multi-range.test.ts

@@ -58,4 +58,38 @@ describe('multiple range selection', () => {
     // outside every range
     expect(s.getCellRangeEdges(2, 2)).toBeNull()
   })
+
+  it('cellSelectionState folds active cell, range edges and fill handle into one value', () => {
+    const ctx = makeCtx()
+    ctx.activeCell = { rowIndex: 1, colIndex: 1, cellId: null }
+    ctx.fillHandleCell = { rowIndex: 1, colIndex: 1 }
+    const s = createSelection(ctx)
+    s.setSelection(0, 0)
+    s.extendSelection(1, 1)
+
+    // The focus corner: active, on the bottom-right edges, carries the handle.
+    expect(s.cellSelectionState(1, 1)).toEqual({
+      active: true,
+      edges: { top: false, bottom: true, left: false, right: true },
+      fillHandle: true,
+    })
+    // Another cell of the range: in the range, not active, no handle.
+    expect(s.cellSelectionState(0, 1)).toEqual({
+      active: false,
+      edges: { top: true, bottom: false, left: false, right: true },
+      fillHandle: false,
+    })
+    // A plain cell is `null`, not an all-false object, so the view can tell
+    // "nothing changed here" by identity.
+    expect(s.cellSelectionState(5, 5)).toBeNull()
+  })
+
+  it('cellSelectionState reports the active cell even with no range anchored', () => {
+    const ctx = makeCtx()
+    ctx.activeCell = { rowIndex: 2, colIndex: 3, cellId: null }
+    ctx.fillHandleCell = null
+    const s = createSelection(ctx)
+    expect(s.cellSelectionState(2, 3)).toEqual({ active: true, edges: null, fillHandle: false })
+    expect(s.cellSelectionState(2, 4)).toBeNull()
+  })
 })

package/src/selection.test.ts

@@ -75,6 +75,8 @@ function makeCtx(overrides: any = {}) {
     // for plain drag-select. Its own behaviour is covered in move-cells.test.ts.
     trackEdgeScroll: vi.fn(),
     stopEdgeScroll: vi.fn(),
+    // Inline virtualizer sync after a programmatic scroll (scroll-sync.ts).
+    syncScrollNow: vi.fn(),
     grid: {
       setRowSelection,
       setActiveCell,
@@ -367,6 +369,19 @@ describe('createSelection - onCellPointerDown', () => {
     expect(ctx.selectionRange.anchor).toEqual({ rowIndex: 0, colIndex: 0 })
     expect(ctx.selectionRange.focus).toEqual({ rowIndex: 1, colIndex: 1 })
     expect(ctx.activeAtPointerDown).toEqual({ rowIndex: 0, colIndex: 0 })
+    // The active cell stays at the anchor, as in Excel.
+    expect(ctx.grid.setActiveCell).not.toHaveBeenCalled()
+  })
+
+  it('Shift+click on a grid never clicked makes the cell active', () => {
+    const ctx = makeCtx({
+      allRows: [makeDataRow('r0'), makeDataRow('r1')],
+      allColumns: [makeColumn('c0'), makeColumn('c1')],
+      activeCell: null,
+    })
+    const sel = createSelection(ctx)
+    sel.onCellPointerDown(1, 1, { button: 0, shiftKey: true } as any)
+    expect(ctx.grid.setActiveCell).toHaveBeenCalled()
   })
 })
 
@@ -378,7 +393,7 @@ describe('createSelection - onCellPointerEnter / drag', () => {
     expect(ctx.grid.setActiveCell).not.toHaveBeenCalled()
   })
 
-  it('extends selection and moves active cell while dragging', () => {
+  it('extends the selection while dragging and leaves the active cell where the drag began', () => {
     const ctx = makeCtx({
       isDraggingSelection: true,
       selectionRange: { anchor: { rowIndex: 0, colIndex: 0 }, focus: { rowIndex: 0, colIndex: 0 } },
@@ -388,7 +403,7 @@ describe('createSelection - onCellPointerEnter / drag', () => {
     const sel = createSelection(ctx)
     sel.onCellPointerEnter(1, 1)
     expect(ctx.selectionRange.focus).toEqual({ rowIndex: 1, colIndex: 1 })
-    expect(ctx.grid.setActiveCell).toHaveBeenCalled()
+    expect(ctx.grid.setActiveCell).not.toHaveBeenCalled()
   })
 
   it('ignores group rows while dragging', () => {
@@ -649,6 +664,19 @@ describe('createSelection - onCellClick', () => {
     expect(ctx.onCellDoubleClick).toHaveBeenCalledWith(0, 0)
   })
 
+  it('leaves the cell alone on a second click when editOnSecondClick is off', () => {
+    // A sheet: clicking the active cell again is a click, not an edit.
+    const ctx = clickCtx({
+      editingEnabled: true,
+      activeAtPointerDown: { rowIndex: 0, colIndex: 0 },
+      props: { editOnSecondClick: false },
+    })
+    const sel = createSelection(ctx)
+    sel.onCellClick(0, 0)
+    expect(ctx.onCellDoubleClick).not.toHaveBeenCalled()
+    expect(ctx.editingCell).toBeNull()
+  })
+
   it('clears editing when not re-clicking the active cell', () => {
     const ctx = clickCtx({
       editingEnabled: true,

package/src/selection.ts

@@ -14,6 +14,7 @@ import {
   getColumnBaseValue,
   isGroupRow,
 } from "./cell-values";
+import { expandRectToMerges, originOf, endOf } from "./merges";
 
 export function createSelection<
   TFeatures extends TableFeatures = TableFeatures,
@@ -41,7 +42,18 @@ export function createSelection<
   }
 
   function setActiveCell(rowIndex: number, colIndex: number) {
+    // 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,
@@ -64,8 +76,16 @@ export function createSelection<
     if (!ctx.scrollContainer) return;
     if (rowIndex < 0 || rowIndex >= ctx.allRows.length) return;
     if (colIndex < 0 || colIndex >= ctx.allColumns.length) return;
-
-    if (ctx.rowVirtualizationEnabled) {
+    const container = ctx.scrollContainer as HTMLElement;
+    const topBefore = container.scrollTop;
+    const leftBefore = container.scrollLeft;
+    // A frozen row is always in view; only the column may need to move.
+    const frozen: number = ctx.frozenRowCount ?? 0;
+    const frozenBand: number = 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
@@ -116,8 +136,10 @@ export function createSelection<
         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
         }
@@ -170,33 +192,66 @@ export function createSelection<
     } 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: SelectionRange | null) {
     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),
-    };
+    });
   }
 
+  type SelectionRect = { minRow: number; maxRow: number; minCol: number; maxCol: number };
+
+  /** The active range as a rectangle, or null while nothing is anchored. */
+  function activeRangeRect(): SelectionRect | null {
+    return rangeRect(ctx.selectionRange as 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: SelectionRange | null = null;
+  let rectsForRanges: SelectionRange[] | null = null;
+  let rectsMemo: SelectionRect[] = [];
+
   // Every selected rectangle: the committed extra ranges plus the active one.
   // Order matters for copy (added-order); the active range comes last.
-  function getSelectionRects() {
-    const rects = [] as Array<{ minRow: number; maxRow: number; minCol: number; maxCol: number }>;
-    for (const r of (ctx.selectionRanges as SelectionRange[]) ?? []) {
+  // Callers must treat the result as read-only.
+  function getSelectionRects(): SelectionRect[] {
+    const range = ctx.selectionRange as SelectionRange;
+    const ranges = (ctx.selectionRanges as SelectionRange[]) ?? [];
+    if (range === rectsForRange && ranges === rectsForRanges) return rectsMemo;
+    const rects: SelectionRect[] = [];
+    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;
   }
 
@@ -259,6 +314,9 @@ export function createSelection<
     // 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 ||
@@ -270,14 +328,40 @@ export function createSelection<
       }
       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: number, colIndex: number) {
+    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
@@ -395,8 +479,12 @@ export function createSelection<
       ? { 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);
       // Ctrl/Cmd starts an ADDITIONAL range, keeping prior ranges highlighted.
@@ -414,8 +502,9 @@ export function createSelection<
     if (!ctx.isDraggingSelection) return;
     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,
@@ -550,12 +639,13 @@ export function createSelection<
     }
 
     // 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;
     }
@@ -603,6 +693,8 @@ export function createSelection<
     extendSelection,
     isCellInSelectedRange,
     getCellRangeEdges,
+    activeRangeRect,
+    cellSelectionState,
     fillMarqueeEdges,
     getSelectionRects,
     isInFillPreview,

package/src/shortcut-registry.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it, beforeEach, vi } from 'vitest'
+import {
+  registerGridShortcuts,
+  runGridShortcuts,
+  hasGridShortcuts,
+  clearGridShortcuts,
+  type GridCommandContext,
+} from './shortcut-registry'
+
+// The context is a structural type over controller state; nothing in the
+// registry reads it, so a cast of an empty object is enough here. The real
+// shape is covered by command-context.test.ts.
+const cmd = {} as GridCommandContext
+const key = (init: KeyboardEventInit = {}) => new KeyboardEvent('keydown', init)
+
+beforeEach(() => clearGridShortcuts())
+
+describe('shortcut registry', () => {
+  it('reports nothing registered on a fresh grid', () => {
+    expect(hasGridShortcuts()).toBe(false)
+    expect(runGridShortcuts(key(), cmd)).toBe(false)
+  })
+
+  it('runs a registered handler and reports the claim', () => {
+    const handler = vi.fn(() => true)
+    registerGridShortcuts(handler)
+    expect(hasGridShortcuts()).toBe(true)
+    expect(runGridShortcuts(key({ key: 'd' }), cmd)).toBe(true)
+    expect(handler).toHaveBeenCalledOnce()
+  })
+
+  it('falls through when the handler declines', () => {
+    registerGridShortcuts(() => false)
+    expect(runGridShortcuts(key(), cmd)).toBe(false)
+  })
+
+  it('stops at the first handler that claims', () => {
+    const order: string[] = []
+    registerGridShortcuts(() => { order.push('a'); return true })
+    registerGridShortcuts(() => { order.push('b'); return true })
+    runGridShortcuts(key(), cmd)
+    expect(order).toEqual(['a'])
+  })
+
+  it('runs higher priority first regardless of registration order', () => {
+    const order: string[] = []
+    registerGridShortcuts(() => { order.push('low'); return false }, { priority: 1 })
+    registerGridShortcuts(() => { order.push('high'); return false }, { priority: 50 })
+    runGridShortcuts(key(), cmd)
+    expect(order).toEqual(['high', 'low'])
+  })
+
+  it('keeps registration order for equal priorities', () => {
+    const order: string[] = []
+    registerGridShortcuts(() => { order.push('first'); return false })
+    registerGridShortcuts(() => { order.push('second'); return false })
+    runGridShortcuts(key(), cmd)
+    expect(order).toEqual(['first', 'second'])
+  })
+
+  it('replaces rather than stacks when the same id registers twice', () => {
+    const first = vi.fn(() => false)
+    const second = vi.fn(() => false)
+    registerGridShortcuts(first, { id: 'sheet' })
+    registerGridShortcuts(second, { id: 'sheet' })
+    runGridShortcuts(key(), cmd)
+    expect(first).not.toHaveBeenCalled()
+    expect(second).toHaveBeenCalledOnce()
+  })
+
+  it('unregisters through the returned disposer', () => {
+    const handler = vi.fn(() => true)
+    const off = registerGridShortcuts(handler)
+    off()
+    expect(hasGridShortcuts()).toBe(false)
+    expect(runGridShortcuts(key(), cmd)).toBe(false)
+    expect(handler).not.toHaveBeenCalled()
+  })
+
+  it('leaves siblings alone when one disposer runs', () => {
+    const kept = vi.fn(() => false)
+    const off = registerGridShortcuts(() => false, { id: 'gone' })
+    registerGridShortcuts(kept, { id: 'kept' })
+    off()
+    runGridShortcuts(key(), cmd)
+    expect(hasGridShortcuts()).toBe(true)
+    expect(kept).toHaveBeenCalledOnce()
+  })
+
+  it('hands the handler the event and the context it was called with', () => {
+    const handler = vi.fn(() => true)
+    registerGridShortcuts(handler)
+    const event = key({ key: 'ArrowDown', ctrlKey: true })
+    runGridShortcuts(event, cmd)
+    expect(handler).toHaveBeenCalledWith(event, cmd)
+  })
+})