@scalebun-release/react-native 2.5.0

package/src/features/session/ScrollTracker.ts

@@ -0,0 +1,166 @@
+/**
+ * ScaleBun SDK — Scroll Tracker
+ *
+ * Dedicated scroll tracking with settle detection.
+ * Tied to actual scrollable surfaces (ScrollView/FlatList/SectionList)
+ * via the ScaleBunScrollView wrapper — NOT root-level touch tracking.
+ *
+ * Behavior:
+ * - Accumulates scroll delta from onScroll events
+ * - Applies minimum threshold (30px) to filter tiny incidental movements
+ * - Uses 250ms idle window to determine scroll end (settle detection)
+ * - On settle: invokes callback with structured metadata
+ * - Session-bound: dispose() cancels all pending timers
+ * - Resets between scroll gestures
+ */
+
+import { logger } from '../../core/logger/internalLogger';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface ScrollMetadata {
+    totalDeltaX: number;
+    totalDeltaY: number;
+    dominantDirection: 'up' | 'down' | 'left' | 'right';
+    startTs: number;
+    endTs: number;
+    durationMs: number;
+}
+
+export type ScrollSettleCallback = (metadata: ScrollMetadata) => void;
+
+// ─── Configuration ──────────────────────────────────────────────────────────
+
+const MIN_DELTA_THRESHOLD = 30;   // px — filter tiny accidental scrolls
+const SETTLE_IDLE_MS = 250;       // ms — idle window to determine scroll end
+
+// ─── Tracker ────────────────────────────────────────────────────────────────
+
+export class ScrollTracker {
+    private onSettle: ScrollSettleCallback;
+
+    // Accumulation state for current gesture
+    private totalDeltaX = 0;
+    private totalDeltaY = 0;
+    private startTs = 0;
+    private lastEventTs = 0;
+    private tracking = false;
+    private previousOffsetX = 0;
+    private previousOffsetY = 0;
+    private hasBaseline = false;
+
+    // Settle timer
+    private settleTimer: ReturnType<typeof setTimeout> | null = null;
+    private disposed = false;
+
+    constructor(onSettle: ScrollSettleCallback) {
+        this.onSettle = onSettle;
+    }
+
+    /**
+     * Called by ScaleBunScrollView on each scroll event.
+     * Computes delta from content offset changes and accumulates.
+     */
+    onScrollEvent(contentOffsetX: number, contentOffsetY: number): void {
+        if (this.disposed) return;
+
+        const now = Date.now();
+
+        if (!this.hasBaseline) {
+            // First event — establish baseline
+            this.previousOffsetX = contentOffsetX;
+            this.previousOffsetY = contentOffsetY;
+            this.hasBaseline = true;
+            return;
+        }
+
+        const deltaX = contentOffsetX - this.previousOffsetX;
+        const deltaY = contentOffsetY - this.previousOffsetY;
+        this.previousOffsetX = contentOffsetX;
+        this.previousOffsetY = contentOffsetY;
+
+        // Skip zero-movement events
+        if (deltaX === 0 && deltaY === 0) return;
+
+        if (!this.tracking) {
+            this.tracking = true;
+            this.startTs = now;
+            this.totalDeltaX = 0;
+            this.totalDeltaY = 0;
+        }
+
+        this.totalDeltaX += deltaX;
+        this.totalDeltaY += deltaY;
+        this.lastEventTs = now;
+
+        // Reset settle timer on each event
+        if (this.settleTimer) {
+            clearTimeout(this.settleTimer);
+        }
+
+        this.settleTimer = setTimeout(() => {
+            this._onSettle();
+        }, SETTLE_IDLE_MS);
+    }
+
+    /** Cancel all pending state. Called on session end. */
+    dispose(): void {
+        this.disposed = true;
+        if (this.settleTimer) {
+            clearTimeout(this.settleTimer);
+            this.settleTimer = null;
+        }
+        this._resetGesture();
+    }
+
+    // ─── Internal ───────────────────────────────────────────────────────
+
+    private _onSettle(): void {
+        this.settleTimer = null;
+
+        if (!this.tracking) return;
+
+        const absDx = Math.abs(this.totalDeltaX);
+        const absDy = Math.abs(this.totalDeltaY);
+
+        // Apply threshold — filter tiny incidental scroll
+        if (absDx + absDy < MIN_DELTA_THRESHOLD) {
+            this._resetGesture();
+            return;
+        }
+
+        // Determine dominant direction
+        let dominantDirection: ScrollMetadata['dominantDirection'];
+        if (absDy >= absDx) {
+            dominantDirection = this.totalDeltaY > 0 ? 'down' : 'up';
+        } else {
+            dominantDirection = this.totalDeltaX > 0 ? 'right' : 'left';
+        }
+
+        const metadata: ScrollMetadata = {
+            totalDeltaX: Math.round(this.totalDeltaX),
+            totalDeltaY: Math.round(this.totalDeltaY),
+            dominantDirection,
+            startTs: this.startTs,
+            endTs: this.lastEventTs,
+            durationMs: this.lastEventTs - this.startTs,
+        };
+
+        try {
+            this.onSettle(metadata);
+        } catch (err) {
+            logger.error('[ScrollTracker] Settle callback error:', err);
+        }
+
+        this._resetGesture();
+    }
+
+    private _resetGesture(): void {
+        this.tracking = false;
+        this.totalDeltaX = 0;
+        this.totalDeltaY = 0;
+        this.startTs = 0;
+        this.lastEventTs = 0;
+        this.hasBaseline = false;
+    }
+}