@svgrid/grid 3.0.3 → 3.0.5

package/src/merges.ts

@@ -0,0 +1,168 @@
+/**
+ * Merged cells: a rectangle of cells drawn as one, the way a spreadsheet's
+ * Merge & Center does. The grid takes them as `mergedCells`, a list of
+ * origins with their spans in display indices, and this module is the
+ * pure part: an index over them, the questions the renderer, the
+ * selection and the keyboard ask, and nothing that touches the DOM.
+ *
+ * A merge is drawn by its origin td, which takes `rowspan` and `colspan`;
+ * the cells it covers are not emitted. Selection rectangles grow to whole
+ * merges (a merge is selected as one), the active cell inside a merge is
+ * its origin, and an arrow key moving into a merge lands on the origin
+ * and moving out of one steps past its far edge.
+ */
+
+export type MergedCell = {
+  /** Top-left cell of the merge, display indices. */
+  rowIndex: number
+  colIndex: number
+  /** How many rows and columns it covers, 1 or more. */
+  rowSpan: number
+  colSpan: number
+}
+
+export type MergeIndex = {
+  readonly list: ReadonlyArray<MergedCell>
+  /** Every cell a merge covers (origin included) -> its merge. */
+  readonly byCell: ReadonlyMap<string, MergedCell>
+}
+
+export type MergeRect = { minRow: number; maxRow: number; minCol: number; maxCol: number }
+
+const key = (r: number, c: number) => `${r}:${c}`
+
+/** An index over the merges, or null when there are none (the common case). */
+export function buildMergeIndex(merges: ReadonlyArray<MergedCell> | undefined | null): MergeIndex | null {
+  if (!merges || merges.length === 0) return null
+  const byCell = new Map<string, MergedCell>()
+  const list: MergedCell[] = []
+  for (const raw of merges) {
+    const rowSpan = Math.max(1, Math.floor(raw.rowSpan))
+    const colSpan = Math.max(1, Math.floor(raw.colSpan))
+    if (rowSpan === 1 && colSpan === 1) continue
+    const merge = { rowIndex: raw.rowIndex, colIndex: raw.colIndex, rowSpan, colSpan }
+    list.push(merge)
+    for (let r = merge.rowIndex; r < merge.rowIndex + rowSpan; r += 1) {
+      for (let c = merge.colIndex; c < merge.colIndex + colSpan; c += 1) byCell.set(key(r, c), merge)
+    }
+  }
+  return list.length ? { list, byCell } : null
+}
+
+/** The merge covering (r, c), origin included, or undefined. */
+export function mergeAt(index: MergeIndex | null, r: number, c: number): MergedCell | undefined {
+  return index?.byCell.get(key(r, c))
+}
+
+/** Whether (r, c) is inside a merge without being its origin. */
+export function isCovered(index: MergeIndex | null, r: number, c: number): boolean {
+  const m = mergeAt(index, r, c)
+  return !!m && (m.rowIndex !== r || m.colIndex !== c)
+}
+
+/** The origin of the merge (r, c) sits in, or (r, c) itself. */
+export function originOf(index: MergeIndex | null, r: number, c: number): { rowIndex: number; colIndex: number } {
+  const m = mergeAt(index, r, c)
+  return m ? { rowIndex: m.rowIndex, colIndex: m.colIndex } : { rowIndex: r, colIndex: c }
+}
+
+/** The far corner of the merge (r, c) sits in, or (r, c) itself. */
+export function endOf(index: MergeIndex | null, r: number, c: number): { rowIndex: number; colIndex: number } {
+  const m = mergeAt(index, r, c)
+  return m
+    ? { rowIndex: m.rowIndex + m.rowSpan - 1, colIndex: m.colIndex + m.colSpan - 1 }
+    : { rowIndex: r, colIndex: c }
+}
+
+/**
+ * The rectangle grown to hold every merge it touches, to a fixed point: a
+ * merge that pokes out of the rectangle pulls the edge out, which can
+ * reach another merge, and so on, as a spreadsheet's selection does.
+ */
+export function expandRectToMerges(index: MergeIndex | null, rect: MergeRect): MergeRect {
+  if (!index) return rect
+  let { minRow, maxRow, minCol, maxCol } = rect
+  for (let guard = 0; guard < 64; guard += 1) {
+    let grew = false
+    for (const m of index.list) {
+      const r2 = m.rowIndex + m.rowSpan - 1
+      const c2 = m.colIndex + m.colSpan - 1
+      const touches = m.rowIndex <= maxRow && r2 >= minRow && m.colIndex <= maxCol && c2 >= minCol
+      if (!touches) continue
+      if (m.rowIndex < minRow) { minRow = m.rowIndex; grew = true }
+      if (r2 > maxRow) { maxRow = r2; grew = true }
+      if (m.colIndex < minCol) { minCol = m.colIndex; grew = true }
+      if (c2 > maxCol) { maxCol = c2; grew = true }
+    }
+    if (!grew) break
+  }
+  return minRow === rect.minRow && maxRow === rect.maxRow && minCol === rect.minCol && maxCol === rect.maxCol
+    ? rect
+    : { minRow, maxRow, minCol, maxCol }
+}
+
+/**
+ * Where a move from `from` to `next` really lands. A step into a merge
+ * lands on its origin; a step that stays inside the merge the move started
+ * in carries on past its far edge (right from a three-wide merge reaches
+ * the column after it), clamped to the bounds; a step that then lands in
+ * another merge takes that one's origin.
+ */
+export function stepPastMerge(
+  index: MergeIndex | null,
+  from: { rowIndex: number; colIndex: number },
+  next: { rowIndex: number; colIndex: number },
+  bounds: { maxRow: number; maxCol: number },
+): { rowIndex: number; colIndex: number } {
+  if (!index) return next
+  const target = mergeAt(index, next.rowIndex, next.colIndex)
+  if (!target) return next
+  const source = mergeAt(index, from.rowIndex, from.colIndex)
+  if (source !== target) return { rowIndex: target.rowIndex, colIndex: target.colIndex }
+  // Still inside the merge the move began in: keep going in that direction.
+  const dr = Math.sign(next.rowIndex - from.rowIndex)
+  const dc = Math.sign(next.colIndex - from.colIndex)
+  if (dr === 0 && dc === 0) return { rowIndex: target.rowIndex, colIndex: target.colIndex }
+  let rowIndex = next.rowIndex
+  let colIndex = next.colIndex
+  if (dr > 0) rowIndex = target.rowIndex + target.rowSpan
+  else if (dr < 0) rowIndex = target.rowIndex - 1
+  if (dc > 0) colIndex = target.colIndex + target.colSpan
+  else if (dc < 0) colIndex = target.colIndex - 1
+  if (rowIndex < 0 || rowIndex > bounds.maxRow || colIndex < 0 || colIndex > bounds.maxCol) {
+    // Nowhere further to go: the merge itself stays current.
+    return { rowIndex: target.rowIndex, colIndex: target.colIndex }
+  }
+  const landed = mergeAt(index, rowIndex, colIndex)
+  return landed ? { rowIndex: landed.rowIndex, colIndex: landed.colIndex } : { rowIndex, colIndex }
+}
+
+/**
+ * How a td at (r, c) draws inside a rendered window of rows and columns.
+ * A merge is drawn once per window, by the top-left cell of the part of it
+ * the window holds: the origin when the origin is in the window (`origin`),
+ * else the first covered cell the window shows (`continuation`, which
+ * draws the origin's content itself), with the spans clamped to the window
+ * so a table never spans into rows it has not drawn. Every other cell of
+ * the merge is `skip`: no td, the drawn one covers its slot.
+ */
+export type MergeDraw =
+  | { kind: 'skip' }
+  | { kind: 'origin' | 'continuation'; merge: MergedCell; rowSpan: number; colSpan: number }
+
+export function mergeDrawAt(
+  index: MergeIndex | null,
+  r: number,
+  c: number,
+  window: { firstRow: number; lastRow: number; firstCol: number; lastCol: number },
+): MergeDraw | null {
+  const m = mergeAt(index, r, c)
+  if (!m) return null
+  const anchorRow = Math.max(m.rowIndex, window.firstRow)
+  const anchorCol = Math.max(m.colIndex, window.firstCol)
+  if (r !== anchorRow || c !== anchorCol) return { kind: 'skip' }
+  const isOrigin = anchorRow === m.rowIndex && anchorCol === m.colIndex
+  const rowSpan = Math.max(1, Math.min(m.rowIndex + m.rowSpan - r, window.lastRow - r + 1))
+  const colSpan = Math.max(1, Math.min(m.colIndex + m.colSpan - c, window.lastCol - c + 1))
+  return { kind: isOrigin ? 'origin' : 'continuation', merge: m, rowSpan, colSpan }
+}

package/src/pivot.grid.test.ts

@@ -35,27 +35,32 @@ const data: Row[] = [
 const engine = (rows: ReadonlyArray<Record<string, unknown>>) => {
   const byRegion = new Map<string, number>()
   for (const r of rows) byRegion.set(String(r.region), (byRegion.get(String(r.region)) ?? 0) + Number(r.sales))
-  const pivotRows: GridPivotRow[] = [...byRegion].map(([region, total], i) => ({
-    __pivotId: `p${i}`, __pivotDepth: 0, __pivotLabel: region, __pivotParentId: null, __pivotExpandable: false,
-    region, total,
+  const pivotRows: Array<GridPivotRow & { __pivotKind: string }> = [...byRegion].map(([region, total], i) => ({
+    __pivotId: `p${i}`, __pivotDepth: 0, __pivotLabel: region, __pivotParentId: null, __pivotExpandable: false, __pivotKind: 'leaf',
+    region, total, pv_grand__total: total,
   }))
+  const all = [...byRegion.values()].reduce((a, b) => a + b, 0)
+  pivotRows.push({ __pivotId: 'grand', __pivotDepth: 0, __pivotLabel: 'Total', __pivotParentId: null, __pivotExpandable: false, __pivotKind: 'grandTotal', region: 'Total', total: all, pv_grand__total: all })
   return {
     rows: pivotRows,
     columns: [
-      { id: 'region', header: 'Region', field: 'region', width: 140 },
+      { id: '__pivotRowHeader', header: 'Region', field: 'region', width: 140 },
       { id: 'total', header: 'Total sales', field: 'total', width: 140 },
+      { id: 'pv_group__grand', header: 'Grand total', columns: [{ id: 'pv_grand__total', header: 'Total sales', field: 'pv_grand__total', width: 140 }] },
     ] as never,
   }
 }
 
 const tick = () => new Promise<void>((r) => queueMicrotask(r))
 
-function mountGrid() {
+function mountGrid(extra: Record<string, unknown> = {}) {
   const target = document.createElement('div')
+  target.style.width = '1000px'
   document.body.appendChild(target)
   const app = mount(SvGrid, {
     target,
     props: {
+      ...extra,
       data,
       columns: cols,
       features,
@@ -99,4 +104,34 @@ describe('in-grid pivot mode', () => {
     expect(target.textContent).toContain('Total sales')
     expect(target.textContent).toContain('140') // EU 100 + 40
   })
+
+  it('the Chart panel charts the pivot on screen, not the source rows', async () => {
+    registerPivotEngine(engine as never)
+    const { target, destroy } = mountGrid({ charting: { defaultOpen: true, position: 'right' } })
+    cleanup = destroy
+    // The panel and the chart engine are lazy chunks: a few macrotasks.
+    for (let i = 0; i < 6; i += 1) await new Promise((r) => setTimeout(r))
+    const panel = target.querySelector('.sv-grid-chart-panel')!
+    expect(panel).toBeTruthy()
+    // The categories are the pivot's leaf rows and the series its value column;
+    // the grand total is not a bar. The source rows would have drawn three bars
+    // (one per row) or asked for a Group by.
+    const table = panel.querySelector('.sv-grid-chart-sr-only tbody')!
+    const cells = [...table.querySelectorAll('td')].map((td) => td.textContent)
+    expect(cells).toEqual(['EU', '140', 'US', '70'])
+    expect(panel.querySelector('.sv-grid-chart-sr-only thead')!.textContent).toContain('Total sales')
+    // The data pickers are gone and the note says why; Type stays.
+    const labels = [...panel.querySelectorAll('.sv-grid-chart-ctl-lbl')].map((l) => l.textContent)
+    expect(labels).not.toContain('Group by')
+    expect(labels).not.toContain('Value')
+    expect(labels).not.toContain('Aggregate')
+    expect(labels).toContain('Type')
+    expect(panel.querySelector('.sv-grid-chart-pivot-hint')!.textContent).toContain('Charting the pivot')
+    // The type list keeps the shapes a pivot can take.
+    const options = [...panel.querySelectorAll('.sv-grid-chart-ctl select option')].map((o) => (o as HTMLOptionElement).value)
+    expect(options).toContain('line')
+    expect(options).toContain('radar')
+    expect(options).not.toContain('scatter')
+    expect(options).not.toContain('candlestick')
+  })
 })

package/src/row-model.ts

@@ -0,0 +1,146 @@
+/**
+ * `GridRowModel` - one prop instead of eleven.
+ *
+ * A grid backed by a server needs the same wiring every time: hand it the
+ * rows, tell it not to sort or filter locally, forward the sort and the filter
+ * to the backend, report which rows are on screen, say which rows have not
+ * loaded, and delegate selection. Written out by hand that is a dozen props
+ * and a filter-shape conversion that every app gets slightly differently:
+ *
+ * ```svelte
+ * <SvGrid data={s.rows} externalSort externalFilter loading={s.loading}
+ *   onSortingChange={(x) => ctl.setSort(x)}
+ *   onFiltersChange={(f) => ctl.setFilter({ global: f.global,
+ *     columns: Object.fromEntries(f.columns.map((c) => [c.id, { ... }])) })}
+ *   onVisibleRangeChange={(r) => ctl.setViewport(r.startIndex, r.endIndex)}
+ *   ... />
+ * ```
+ *
+ * An object that implements this interface carries all of it, so the same grid
+ * becomes:
+ *
+ * ```svelte
+ * <SvGrid rowModel={ctl} {columns} />
+ * ```
+ *
+ * `createServerDataSource` returns one, and so does the Enterprise server row
+ * model - which is the point of the interface rather than a concrete type: the
+ * grid depends on the SHAPE, never on either implementation, and an app with
+ * its own fetching can satisfy it too.
+ *
+ * Every member except `subscribe` / `getRows` / `isLoading` is optional, and a
+ * prop written explicitly on `<SvGrid>` always wins over the model's answer -
+ * so adopting this is never all-or-nothing.
+ */
+import type { FilterOperator } from './SvGrid.types'
+
+/** The filter state as the grid reports it, straight from `onFiltersChange`. */
+export type GridFilterState = {
+  global: string
+  columns: Array<{
+    id: string
+    operator: FilterOperator
+    value: string
+    valueTo?: string
+    selectedValues?: Array<string>
+  }>
+}
+
+/** The sort the grid hands a row model: column id and direction, in priority order. */
+export type GridRowModelSort = Array<{ id: string; desc: boolean }>
+
+/**
+ * What `<SvGrid rowModel>` consumes: rows, a loading flag, a change
+ * subscription, and whichever optional parts the model implements - sort,
+ * filter, viewport, placeholders, group accessors, selection, filter
+ * values, paging, pinned rows and pivot columns. `createServerDataSource`
+ * and the Enterprise `createServerRowModel` both satisfy it.
+ */
+export type GridRowModel<TData> = {
+  /**
+   * Register a callback for "something changed, re-read me". Returns an
+   * unsubscribe function, which the grid calls on unmount.
+   */
+  subscribe(onChange: () => void): () => void
+  /** The rows to render, including any placeholders for unloaded ones. */
+  getRows(): ReadonlyArray<TData>
+  /** True while a fetch is in flight, for the loading overlay. */
+  isLoading(): boolean
+  /** Stable row id. Required once selection or editing is involved. */
+  getRowId?(row: TData, index: number): string
+  /** Sort on the server. Present means "do not sort locally". */
+  setSort?(sort: GridRowModelSort): void
+  /** Filter on the server. Present means "do not filter locally". */
+  setFilter?(filters: GridFilterState): void
+  /** Which rows are on screen, so a block-loading model knows what to fetch. */
+  setViewport?(startIndex: number, endIndex: number): void
+  /** Why a row has no data yet, or null when it does. */
+  rowPlaceholder?(row: TData, rowIndex: number): 'loading' | 'failed' | null
+  /** Retry the failed block a placeholder row belongs to. */
+  retryRow?(row: TData, rowIndex: number): void
+  /** Group / tree accessors, for the grid's treegrid keyboard and ARIA. */
+  group?: {
+    isGroup: (row: TData) => boolean
+    level: (row: TData) => number
+    expanded?: (row: TData) => boolean
+    onToggle: (row: TData) => void
+  }
+  /** Selection the grid does not own - see the `rowSelectionModel` prop. */
+  selection?: {
+    isSelected: (rowId: string, row: TData) => boolean
+    headerState: () => 'none' | 'some' | 'all'
+    toggle: (rowId: string, row: TData, next: boolean) => void
+    toggleAll: (next: boolean) => void
+    selectedCount?: () => number | null
+    bulkUpdate?: (patch: Record<string, unknown>) => Promise<number>
+  }
+  /** Distinct values for a column's set filter, fetched from the server. */
+  filterValues?(columnId: string): Promise<Array<string>>
+  /** Server-side paging. Omit it for infinite scrolling. */
+  pagination?: {
+    pageIndex: number
+    pageSize: number
+    rowCount: number
+    setPage(pageIndex: number): void
+    setPageSize(pageSize: number): void
+    /** Choices for the footer's page-size selector. */
+    pageSizes?: number[]
+    /**
+     * Ask the grid for as many rows as its body fits: it measures and calls
+     * `setPageSize` whenever the fit changes.
+     */
+    autoPageSize?: boolean
+  }
+  /** Rows to pin above / below the scrolling body - a grand total, say. */
+  readonly pinnedTopRows?: ReadonlyArray<TData>
+  readonly pinnedBottomRows?: ReadonlyArray<TData>
+  /**
+   * Columns that replace the grid's `columns` while the model is in pivot
+   * mode, or null. Read after every change notification.
+   */
+  readonly pivotResultColumns?: ReadonlyArray<unknown> | null
+}
+
+/**
+ * Turn the grid's filter payload into the column-keyed map a `ServerRequest`
+ * carries. Exported because a hand-written `GridRowModel` needs exactly this
+ * conversion, and copying it is how the two shapes drift apart.
+ */
+export function toServerFilterColumns(
+  filters: GridFilterState,
+): Record<
+  string,
+  { operator: string; value: string; valueTo?: string; selectedValues?: Array<string> }
+> {
+  return Object.fromEntries(
+    filters.columns.map((c) => [
+      c.id,
+      {
+        operator: c.operator,
+        value: c.value,
+        ...(c.valueTo !== undefined ? { valueTo: c.valueTo } : {}),
+        ...(c.selectedValues !== undefined ? { selectedValues: c.selectedValues } : {}),
+      },
+    ]),
+  )
+}

package/src/row-resize.test.ts

@@ -209,6 +209,50 @@ describe('rowResize - strip injection', () => {
 // Drag lifecycle
 // ---------------------------------------------------------------------------
 
+describe('rowResize - double-click', () => {
+  it('asks for an autosize of the row and keeps the click from the row itself', () => {
+    const { host, rows } = buildGrid([{ rowIndex: 0 }, { rowIndex: 1 }])
+    track(host)
+    const onAutosize = vi.fn()
+    const rowSaw = vi.fn()
+    rows[1]!.addEventListener('dblclick', rowSaw)
+    const onResize = vi.fn()
+    const action = rowResize(host, { onResize, onAutosize })
+    const strip = stripOf(rows[1]!)!
+    // Two presses on one strip inside 400ms are a double-click.
+    strip.dispatchEvent(pointer('pointerdown', { clientY: 100 }))
+    window.dispatchEvent(pointer('pointerup', { clientY: 100 }))
+    strip.dispatchEvent(pointer('pointerdown', { clientY: 100 }))
+    expect(onAutosize).toHaveBeenCalledWith(1)
+    // No drag started, so nothing to release.
+    expect(strip.classList.contains('is-resizing')).toBe(false)
+    window.dispatchEvent(pointer('pointerup', { clientY: 100 }))
+    // The first press's release reported the unchanged height; the second
+    // press started no drag.
+    expect(onResize).toHaveBeenCalledTimes(1)
+    expect(rowSaw).not.toHaveBeenCalled()
+    action.destroy()
+  })
+
+  it('does nothing without an onAutosize handler', () => {
+    const { host, rows } = buildGrid([{ rowIndex: 0 }])
+    track(host)
+    const rowSaw = vi.fn()
+    rows[0]!.addEventListener('dblclick', rowSaw)
+    const onResize = vi.fn()
+    const action = rowResize(host, { onResize })
+    const strip = stripOf(rows[0]!)!
+    strip.dispatchEvent(pointer('pointerdown', { clientY: 100 }))
+    window.dispatchEvent(pointer('pointerup', { clientY: 100 }))
+    strip.dispatchEvent(pointer('pointerdown', { clientY: 100 }))
+    // Without a handler the second press is an ordinary drag start.
+    expect(strip.classList.contains('is-resizing')).toBe(true)
+    window.dispatchEvent(pointer('pointerup', { clientY: 100 }))
+    expect(rowSaw).not.toHaveBeenCalled()
+    action.destroy()
+  })
+})
+
 describe('rowResize - drag', () => {
   it('reports the new height on pointerup and fires move callbacks', () => {
     const { host, rows } = buildGrid([{ rowIndex: 0 }])

package/src/row-resize.ts

@@ -33,6 +33,9 @@ export type RowResizeOptions = {
   onResize: (rowIndex: number, height: number) => void
   /** Optional callback fired during the drag (every pointermove). */
   onResizeMove?: (rowIndex: number, height: number) => void
+  /** Double-click on the strip: size the row to its content, the
+   *  spreadsheet gesture. Without it a double-click does nothing. */
+  onAutosize?: (rowIndex: number) => void
   /** Min row height in px. Default 20. */
   min?: number
   /** Max row height in px. Default 320. */
@@ -63,6 +66,8 @@ type ActiveDrag = {
 export function rowResize(node: HTMLElement, opts: RowResizeOptions) {
   let current = opts
   let drag: ActiveDrag | null = null
+  /** The last press on a strip, for telling a double-click from two drags. */
+  let lastPress: { rowIndex: number; at: number } | null = null
 
   function rowIndexOf(tr: HTMLTableRowElement): number {
     const dataRow = tr.querySelector<HTMLElement>('[data-svgrid-row]')
@@ -133,6 +138,18 @@ export function rowResize(node: HTMLElement, opts: RowResizeOptions) {
     if (!Number.isFinite(rowIndex)) return
     e.preventDefault()
     e.stopPropagation()
+    // The second press of a double-click: size the row to its content
+    // instead of starting another drag. Timed here rather than read from
+    // a dblclick event, whose target is the row once the first press's
+    // resize has re-rendered the strip; pointerdown carries no count.
+    const now = e.timeStamp
+    const again = lastPress !== null && lastPress.rowIndex === rowIndex && now - lastPress.at < 400
+    lastPress = { rowIndex, at: now }
+    if (again && current.onAutosize) {
+      lastPress = null
+      current.onAutosize(rowIndex)
+      return
+    }
     t.classList.add('is-resizing')
     drag = {
       rowIndex,

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()
+  })
 })