Enhancement: Refactor GridRowScrollPinning to Hybrid rAF Engine (#9391)

tobiu · tobiu · commit 92ca86d730b5 · 2026-03-08T15:29:58.000+01:00
- Rewrote GridRowScrollPinning to use a continuous requestAnimationFrame loop driven by native scroll events to achieve perfect 60fps syncing against the massive DOM layer.
- VDOM delta updates now only modify the internal baseline state without touching the DOM.
- Implemented hysteresis logic (isPinned) to maintain stable pinning states.
- Reverted the addon registration back to the afterSetMounted lifecycle hook, as it now requires DOM node access for event listeners.
diff --git a/src/grid/ScrollManager.mjs b/src/grid/ScrollManager.mjs
@@ -87,9 +87,11 @@ class ScrollManager extends Base {
      */
     afterSetMounted(value, oldValue) {
         if (value) {
-            this.dragScroll && this.updateDragScrollAddon(true)
+            this.dragScroll       && this.updateDragScrollAddon(true);
+            this.rowScrollPinning && this.updateRowScrollPinningAddon(true)
         } else if (oldValue) {
-            this.updateDragScrollAddon(false)
+            this.updateDragScrollAddon(false);
+            this.updateRowScrollPinningAddon(false)
         }
     }
 
@@ -98,7 +100,9 @@ class ScrollManager extends Base {
      * @param {Boolean} oldValue
      */
     afterSetRowScrollPinning(value, oldValue) {
-        this.updateRowScrollPinningAddon(value)
+        if (this.mounted) {
+            this.updateRowScrollPinningAddon(value)
+        }
     }
 
     /**
diff --git a/src/main/addon/GridRowScrollPinning.mjs b/src/main/addon/GridRowScrollPinning.mjs
@@ -1,19 +1,21 @@
 import Base      from './Base.mjs';
 import DomAccess from '../DomAccess.mjs';
 
-const translateRegex = /translate3d\(0px,\s*(-?\d+(?:\.\d+)?)px,\s*0px\)/;
-
 /**
- * @summary Main Thread Addon for High-Performance Grid Row Scroll Pinning.
+ * @summary Main Thread Addon for High-Performance Grid Row Scroll Pinning (Hybrid Engine).
  *
- * This addon intercepts VDOM deltas for grid rows just before they are applied to the DOM.
- * It compares the `scrollTop` state of the App Worker (when the deltas were generated)
- * against the actual, current `scrollTop` of the Grid Body in the Main Thread.
+ * This addon uses a Hybrid rAF + Scroll Listener architecture to prevent visual
+ * row tearing during rapid scrolling (e.g., dragging the scrollbar thumb).
  *
- * If there is a discrepancy (e.g., due to fast native scrolling), it surgically modifies
- * the `translate3d` CSS transform values of the row deltas inline. This visually "pins"
- * the rows to their correct physical position on the screen, completely eliminating
- * scroll thrashing and white flashes during rapid scrolling.
+ * **The Hybrid Architecture:**
+ * 1.  **Stateful Updates:** VDOM updates from the App Worker do NOT trigger DOM mutations.
+ *     They merely update an internal `workerScrollTop` state variable.
+ * 2.  **Scroll Driven:** A native `scroll` listener on the Grid Wrapper triggers the logic.
+ * 3.  **rAF Debouncing:** The scroll event schedules a single `requestAnimationFrame` callback.
+ * 4.  **Optical Pinning:** Inside the rAF loop, if the `deltaY` (Actual Scroll - Worker Scroll)
+ *     exceeds a large threshold (e.g. 30 rows), a CSS `translateY` is applied to the
+ *     *entire Grid Body Content Node*. This instantly slides the perfectly-laid-out pool
+ *     of rows to stay on screen, bypassing the 50ms+ VDOM worker latency.
  *
  * @class Neo.main.addon.GridRowScrollPinning
  * @extends Neo.main.addon.Base
@@ -39,21 +41,64 @@ class GridRowScrollPinning extends Base {
     }
 
     /**
+     * Stores state per registered Grid Body.
+     * Shape: { id, bodyId, wrapperNode, contentNode, workerScrollTop, rowHeight, ticking }
      * @member {Map<String, Object>} registrations=new Map()
      * @protected
      */
     registrations = new Map()
 
+    /**
+     * We bind the scroll handler once to avoid creating new functions per registration.
+     * @member {Function} boundOnScroll
+     * @protected
+     */
+    boundOnScroll = this.onScroll.bind(this)
+
     /**
      * @param {Object} config
      */
     construct(config) {
         super.construct(config);
-
         Neo.main.DeltaUpdates.on('update', this.onDeltaUpdate, this)
     }
 
     /**
+     * Executes inside the rAF loop. Reads DOM, does math, mutates DOM.
+     * @param {String} id
+     * @protected
+     */
+    applyPinning(id) {
+        let me    = this,
+            state = me.registrations.get(id);
+
+        if (!state || !state.wrapperNode || !state.contentNode) {
+            if (state) state.ticking = false;
+            return
+        }
+
+        let actualScrollTop = state.wrapperNode.scrollTop || 0,
+            deltaY          = actualScrollTop - state.workerScrollTop,
+            absDelta        = Math.abs(deltaY);
+
+        // Hysteresis: If we are already pinned, stay pinned until the worker is within 2px.
+        // If we are NOT pinned, engage pinning if the worker lags by more than 1 row.
+        let shouldPin = state.isPinned ? (absDelta > 2) : (absDelta > state.rowHeight);
+
+        if (shouldPin) {
+            state.contentNode.style.transform = `translate3d(0px, ${deltaY}px, 0px)`;
+            state.isPinned = true;
+        } else if (state.contentNode.style.transform) {
+            // Worker has caught up to the scroll position. Clear the optical shift.
+            state.contentNode.style.transform = null;
+            state.isPinned = false;
+        }
+
+        state.ticking = false
+    }
+
+    /**
+     * Updates internal baseline state. Does NOT mutate the DOM.
      * @param {Object} data The event payload from Neo.main.DeltaUpdates
      * @protected
      */
@@ -65,75 +110,88 @@ class GridRowScrollPinning extends Base {
             return
         }
 
-        me.registrations.forEach(registration => {
-            let bodyMeta = meta[registration.bodyId];
+        me.registrations.forEach(state => {
+            let bodyMeta = meta[state.bodyId];
 
             if (bodyMeta) {
-                // The actual scroll container in the DOM is the wrapper node
-                let wrapperId       = registration.bodyId + '__wrapper',
-                    actualScrollTop = DomAccess.getElement(wrapperId)?.scrollTop || 0,
-                    deltaY          = actualScrollTop - bodyMeta.scrollTop;
-
-                // Engage pinning if the worker is off by more than 2 rows
-                if (Math.abs(deltaY) > (bodyMeta.rowHeight * 2)) {
-                    me.pinRows(deltas, registration.bodyId, deltaY)
+                // Silently update the baseline state. The rAF loop will consume this on the next scroll tick.
+                state.workerScrollTop = bodyMeta.scrollTop;
+                state.rowHeight       = bodyMeta.rowHeight;
+
+                // CRITICAL: If the worker sends an update after the user stops scrolling,
+                // we must re-evaluate to clear the stale transform!
+                if (!state.ticking) {
+                    state.ticking = true;
+                    requestAnimationFrame(() => me.applyPinning(state.id))
                 }
             }
         })
     }
 
     /**
-     * Surgically modifies the translate3d string for row updates.
-     * @param {Object[]} deltas
-     * @param {String} bodyId
-     * @param {Number} deltaY
+     * Triggered by native browser scroll. Debounces via rAF.
+     * @param {Event} event
      * @protected
      */
-    pinRows(deltas, bodyId, deltaY) {
-        let i        = 0,
-            len      = deltas.length,
-            rowIdRef = bodyId + '__row-',
-            delta, transformMatch, currentY;
-
-        for (; i < len; i++) {
-            delta = deltas[i];
-
-            // In VDOM diffs, attribute updates often omit the 'action' property,
-            // relying on DeltaUpdates to default to 'updateNode'.
-            if (
-                (!delta.action || delta.action === 'updateNode') &&
-                delta.id?.startsWith(rowIdRef) &&
-                delta.style?.transform
-            ) {
-                transformMatch = delta.style.transform.match(translateRegex);
-
-                if (transformMatch && transformMatch[1]) {
-                    currentY = parseFloat(transformMatch[1]);
-                    // Apply the inline mutation
-                    delta.style.transform = `translate3d(0px, ${currentY + deltaY}px, 0px)`
-                }
+    onScroll(event) {
+        let me      = this,
+            wrapper = event.target,
+            state;
+
+        // Find which registration this scroll event belongs to based on the wrapper node
+        for (const reg of me.registrations.values()) {
+            if (reg.wrapperNode === wrapper) {
+                state = reg;
+                break
             }
         }
+
+        if (state && !state.ticking) {
+            state.ticking = true;
+            requestAnimationFrame(() => me.applyPinning(state.id))
+        }
     }
 
     /**
-     * Registers a grid for row scroll pinning.
+     * Registers a grid for row scroll pinning and attaches native scroll listener.
      * @param {Object} data
      * @param {String} data.bodyId The ID of the grid body
      * @param {String} data.id     Unique identifier for the registration (e.g. ScrollManager id)
      */
     register({bodyId, id}) {
-        this.registrations.set(id, {bodyId, id})
+        let me          = this,
+            wrapperNode = DomAccess.getElement(bodyId + '__wrapper'),
+            contentNode = DomAccess.getElement(bodyId);
+
+        if (wrapperNode && contentNode) {
+            me.registrations.set(id, {
+                id,
+                bodyId,
+                wrapperNode,
+                contentNode,
+                rowHeight      : 0,
+                ticking        : false,
+                workerScrollTop: 0
+            });
+
+            wrapperNode.addEventListener('scroll', me.boundOnScroll, {passive: true})
+        }
     }
 
     /**
-     * Unregisters a grid.
+     * Unregisters a grid and cleans up listeners.
      * @param {Object} data
      * @param {String} data.id
      */
     unregister({id}) {
-        this.registrations.delete(id)
+        let me    = this,
+            state = me.registrations.get(id);
+
+        if (state && state.wrapperNode) {
+            state.wrapperNode.removeEventListener('scroll', me.boundOnScroll);
+            me.registrations.delete(id)
+        }
     }
 }
 
-export default Neo.setupClass(GridRowScrollPinning);
+export default Neo.setupClass(GridRowScrollPinning);
