feat: use native browser scroll for wheel with scroll overlay

Replace custom wheel event handling with a transparent scroll overlay div
that leverages the browser's native scroll behavior. This provides free
momentum scrolling, smooth scrolling, and trackpad gesture support.

- Add scroll overlay div (overflow: auto, touch-action: none) on top of canvas
- Remove wheel event handler from EventManager (browser handles it natively)
- Keep manual touch scroll with custom momentum (for selection drag compat)
- Bidirectional sync between overlay scrollTop/Left and scrollTopRef/LeftRef
- Safari compat via injected ::-webkit-scrollbar { display: none } style

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ohah

packages/react-wasm-table/src/adapter/__tests__/event-manager.test.ts

@@ -996,19 +996,14 @@ describe("EventManager", () => {
       expect(coords.viewportX).toBe(56);
     });
 
-    it("passes native WheelEvent to onScroll", () => {
+    it("wheel scroll is handled natively by overlay (no onScroll from wheel)", () => {
+      // Wheel events no longer trigger onScroll — the scroll overlay div
+      // handles them natively via overflow: auto.
       const onScroll = mock((_dy: number, _dx: number, _native: WheelEvent | null) => {});
       em.attach(canvas, { onScroll });
 
       canvas.dispatchEvent(new WheelEvent("wheel", { deltaY: 100, deltaX: 0, bubbles: true }));
-      expect(onScroll).toHaveBeenCalledTimes(1);
-      const [dy, _dx, native] = onScroll.mock.calls[0] as unknown as [
-        number,
-        number,
-        WheelEvent | null,
-      ];
-      expect(dy).toBe(100);
-      expect(native).toBeInstanceOf(WheelEvent);
+      expect(onScroll).toHaveBeenCalledTimes(0);
     });
 
     it("passes EventCoords with scrollLeft correction", () => {

packages/react-wasm-table/src/adapter/event-manager.ts

@@ -10,6 +10,8 @@ const DOUBLE_TAP_INTERVAL = 300; // ms between taps for double-tap
 const DOUBLE_TAP_DISTANCE = 20; // max px between taps for double-tap
 const LONG_PRESS_DURATION = 500; // ms hold → selection drag mode
 const MOUSE_DRAG_THRESHOLD = 5; // px movement before mousemove triggers drag-extend
+const MOMENTUM_FRICTION = 0.95; // velocity multiplier per frame (lower = more friction)
+const MOMENTUM_MIN_VELOCITY = 0.5; // px/frame — stop animation below this
 const RESIZE_HANDLE_ZONE = 5; // px from header right edge for resize handle
 const DRAG_HANDLE_ZONE = 20; // px zone for column DnD grip handle (left of resize zone)
 
@@ -80,11 +82,9 @@ export interface GridEventHandlers {
   ) => boolean | void;
 }
 
-/** Options for deltaMode normalization. */
+/** @deprecated Wheel scroll is now handled natively by the scroll overlay. */
 export interface ScrollNormalization {
-  /** Pixels per line for deltaMode=1 (DOM_DELTA_LINE). Typically rowHeight. */
   lineHeight: number;
-  /** Pixels per page for deltaMode=2 (DOM_DELTA_PAGE). Typically viewport height. */
   pageHeight: number;
 }
 
@@ -154,6 +154,12 @@ export class EventManager {
   private lastTapX = 0;
   private lastTapY = 0;
 
+  // Momentum / inertia state (touch only — wheel uses native scroll)
+  private momentumRafId: number | null = null;
+  private velocityX = 0;
+  private velocityY = 0;
+  private lastMoveTime = 0;
+
   // Mouse drag state
   private mouseDownPos: { x: number; y: number } | null = null;
   private mouseDragActive = false;
@@ -177,6 +183,35 @@ export class EventManager {
     coords: EventCoords;
   } | null = null;
 
+  /** Cancel any running touch momentum animation. */
+  private stopMomentum(): void {
+    if (this.momentumRafId !== null) {
+      cancelAnimationFrame(this.momentumRafId);
+      this.momentumRafId = null;
+    }
+    this.velocityX = 0;
+    this.velocityY = 0;
+  }
+
+  /** Start momentum deceleration animation (shared by touch and wheel). */
+  private startMomentum(onScroll: GridEventHandlers["onScroll"]): void {
+    const speed = Math.sqrt(this.velocityX ** 2 + this.velocityY ** 2);
+    if (speed < MOMENTUM_MIN_VELOCITY) return;
+
+    const tick = () => {
+      this.velocityX *= MOMENTUM_FRICTION;
+      this.velocityY *= MOMENTUM_FRICTION;
+      const curSpeed = Math.sqrt(this.velocityX ** 2 + this.velocityY ** 2);
+      if (curSpeed < MOMENTUM_MIN_VELOCITY) {
+        this.stopMomentum();
+        return;
+      }
+      onScroll?.(this.velocityY, this.velocityX, null);
+      this.momentumRafId = requestAnimationFrame(tick);
+    };
+    this.momentumRafId = requestAnimationFrame(tick);
+  }
+
   /** Update the layouts used for hit-testing. */
   setLayouts(headerLayouts: CellLayout[], rowLayouts: CellLayout[]): void {
     this.headerLayouts = headerLayouts;
@@ -265,11 +300,14 @@ export class EventManager {
     return findCell(x, y, this.rowLayouts) ?? findNearestCell(x, y, this.rowLayouts);
   }
 
-  /** Attach event listeners to a canvas element. */
+  /**
+   * Attach event listeners to an element (typically the scroll overlay div).
+   * Wheel scroll is handled natively by the overlay's `overflow: auto`.
+   */
   attach(
-    canvas: HTMLCanvasElement,
+    canvas: HTMLElement,
     handlers: GridEventHandlers,
-    scrollNorm?: ScrollNormalization,
+    _scrollNorm?: ScrollNormalization,
   ): void {
     this.detach();
     this.controller = new AbortController();
@@ -629,29 +667,9 @@ export class EventManager {
       { signal },
     );
 
-    const lineH = scrollNorm?.lineHeight ?? 36;
-    const pageH = scrollNorm?.pageHeight ?? 400;
-
-    canvas.addEventListener(
-      "wheel",
-      (e: WheelEvent) => {
-        e.preventDefault();
-        let dy = e.deltaY;
-        let dx = e.deltaX;
-        // Normalize deltaMode to pixels
-        if (e.deltaMode === 1) {
-          // DOM_DELTA_LINE (Firefox mouse wheel)
-          dy *= lineH;
-          dx *= lineH;
-        } else if (e.deltaMode === 2) {
-          // DOM_DELTA_PAGE
-          dy *= pageH;
-          dx *= pageH;
-        }
-        handlers.onScroll?.(dy, dx, e);
-      },
-      { signal, passive: false },
-    );
+    // Wheel scroll is handled natively by the overlay's overflow: auto.
+    // No wheel event listener needed — the browser provides momentum,
+    // smooth scrolling, and trackpad gesture support automatically.
 
     // ── Touch event listeners ──────────────────────────────────────────
 
@@ -681,6 +699,9 @@ export class EventManager {
         // Fire user touch callback — preventDefault cancels all internal handling
         if (handlers.onTouchStart?.(e, coords, hitTest) === false) return;
 
+        // Stop any running momentum animation when a new touch begins
+        this.stopMomentum();
+
         this.touchState = {
           startX: touch.clientX,
           startY: touch.clientY,
@@ -778,6 +799,17 @@ export class EventManager {
           if (ts.isScrolling) {
             // Invert: finger moves down → content scrolls up (negative deltaY)
             handlers.onScroll?.(-dy, -dx, null);
+
+            // Track velocity for momentum
+            const now = performance.now();
+            const dt = now - this.lastMoveTime;
+            if (dt > 0 && dt < 100) {
+              // Use exponential smoothing to avoid jitter
+              const alpha = 0.8;
+              this.velocityX = alpha * (-dx / dt) * 16 + (1 - alpha) * this.velocityX;
+              this.velocityY = alpha * (-dy / dt) * 16 + (1 - alpha) * this.velocityY;
+            }
+            this.lastMoveTime = now;
           }
         }
 
@@ -814,6 +846,11 @@ export class EventManager {
           return;
         }
 
+        // Start momentum animation if scrolling with enough velocity
+        if (ts.isScrolling && !ts.isSelectionDrag) {
+          this.startMomentum(handlers.onScroll);
+        }
+
         // Tap detection
         const now = performance.now();
         const elapsed = now - ts.startTime;
@@ -878,6 +915,8 @@ export class EventManager {
       clearTimeout(this.touchState.longPressTimer);
       this.touchState.longPressTimer = null;
     }
+    // Note: do NOT stop touch momentum on detach — allow inertia to continue
+    // across React effect re-runs (same reason as touchState preservation).
     this.controller?.abort();
     this.controller = null;
   }

packages/react-wasm-table/src/react/Grid.tsx

@@ -1,4 +1,15 @@
 import { useRef, useMemo, useEffect, useCallback } from "react";
+
+// Inject global CSS to hide scrollbar in scroll overlay (Safari doesn't support scrollbar-width: none)
+const SCROLL_OVERLAY_STYLE_ID = "__rwt-scroll-overlay-style";
+function ensureScrollOverlayStyle() {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(SCROLL_OVERLAY_STYLE_ID)) return;
+  const style = document.createElement("style");
+  style.id = SCROLL_OVERLAY_STYLE_ID;
+  style.textContent = `[data-scroll-overlay]::-webkit-scrollbar { display: none; }`;
+  document.head.appendChild(style);
+}
 import type { GridProps, Theme } from "../types";
 import { DEFAULT_THEME } from "../types";
 import { resolveColumns } from "../resolve-columns";
@@ -144,7 +155,10 @@ export function Grid({
   _parsedBorderStyles,
   _onVisibleRangeChange,
 }: GridProps) {
+  ensureScrollOverlayStyle();
+
   const canvasRef = useRef<HTMLCanvasElement>(null);
+  const scrollOverlayRef = useRef<HTMLDivElement>(null);
   const editorRef = useRef<HTMLDivElement>(null);
   const vScrollbarRef = useRef<HTMLDivElement>(null);
   const hScrollbarRef = useRef<HTMLDivElement>(null);
@@ -269,6 +283,7 @@ export function Grid({
     width,
     columnRegistry,
     invalidate,
+    scrollOverlayRef,
   });
 
   // Hook composition
@@ -485,6 +500,7 @@ export function Grid({
     engine,
     memoryBridgeRef,
     canvasRef,
+    scrollOverlayRef,
     columnRegistry,
     data,
     stringTableRef,
@@ -527,6 +543,7 @@ export function Grid({
 
   useEventAttachment({
     canvasRef,
+    scrollOverlayRef,
     eventManagerRef,
     editorManagerRef,
     table: tableProp,
@@ -715,8 +732,27 @@ export function Grid({
         <canvas
           ref={canvasRef}
           data-grid-canvas
-          style={{ display: "block", touchAction: "none", width, height }}
+          style={{ display: "block", width, height, pointerEvents: "none" }}
         />
+        {/* Scroll overlay: native browser scroll for wheel (momentum/smooth),
+            touch-action: none so touch is handled manually by EventManager */}
+        <div
+          ref={scrollOverlayRef}
+          data-scroll-overlay
+          style={{
+            position: "absolute",
+            top: 0,
+            left: 0,
+            width,
+            height,
+            overflow: "auto",
+            touchAction: "none",
+            scrollbarWidth: "none",
+            zIndex: 1,
+          }}
+        >
+          <div data-scroll-spacer style={{ pointerEvents: "none" }} />
+        </div>
         <div
           ref={editorRef}
           style={{
@@ -817,7 +853,10 @@ export function Grid({
                       si._domHandlers?.onKeyDown?.(e);
                     }}
                     onWheel={(e) => {
-                      canvasRef.current?.dispatchEvent(new WheelEvent("wheel", e.nativeEvent));
+                      scrollOverlayRef.current?.scrollBy({
+                        top: e.nativeEvent.deltaY,
+                        left: e.nativeEvent.deltaX,
+                      });
                     }}
                     style={selectStyle}
                   />