@repliqo/sdk-react-native 0.3.8 → 0.4.1

package/src/components/useRepliqoScrollTracking.ts

@@ -0,0 +1,366 @@
+import { useCallback, useRef, useEffect } from 'react';
+import {
+  Keyboard,
+  Dimensions,
+  type NativeSyntheticEvent,
+  type NativeScrollEvent,
+  type LayoutChangeEvent,
+} from 'react-native';
+import { AppAnalytics } from '../core/client';
+
+/** Minimum scroll delta (px) to trigger a new tile capture. */
+const MIN_DELTA_PX = 20;
+/** Debounce: wait this long after scroll stops before capturing. */
+const DEBOUNCE_MS = 250;
+/** Throttle: minimum time between tile captures. */
+const THROTTLE_MS = 400;
+/**
+ * During continuous scroll, force a capture every this many ms.
+ * Ensures tiles are captured even during fast, uninterrupted scrolls
+ * where the user never pauses long enough for the debounce to fire.
+ */
+const SCROLL_INTERVAL_MS = 1200;
+/**
+ * During scroll, throttle window-bounds re-measurement to at most once per
+ * this many ms. Bounds rarely change while scrolling, but we still want to
+ * catch orientation changes / keyboard / overlay animations.
+ */
+const REMEASURE_THROTTLE_MS = 500;
+/**
+ * The continuous-scroll interval self-stops when no scroll event has been
+ * seen for this long. Programmatic scrolls (scrollTo / Animated) fire
+ * onScroll but never onScrollEndDrag/onMomentumScrollEnd — without this,
+ * the interval would keep running until unmount.
+ */
+const INTERVAL_IDLE_STOP_MS = SCROLL_INTERVAL_MS * 2;
+
+let scrollViewIdCounter = 0;
+const nextScrollViewId = () => `repliqo-scroll-${++scrollViewIdCounter}`;
+
+export interface RepliqoScrollHandlers {
+  /** Attach as the scrollable's ref (also forwards to the user's ref). */
+  setRef: (node: unknown) => void;
+  onScroll: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+  onScrollEndDrag: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+  onMomentumScrollEnd: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+  onLayout: (event: LayoutChangeEvent) => void;
+  onContentSizeChange: (w: number, h: number) => void;
+}
+
+interface ForwardedHandlers {
+  onScroll?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+  onScrollEndDrag?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+  onMomentumScrollEnd?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+  onLayout?: (event: LayoutChangeEvent) => void;
+  onContentSizeChange?: (w: number, h: number) => void;
+}
+
+/**
+ * Shared scroll-analytics behavior behind RepliqoScrollView and
+ * RepliqoFlatList:
+ *
+ *  1. Reports scroll offset for accurate heatmap touch coords
+ *  2. Captures viewport tiles on scroll stops AND during continuous
+ *     scroll for collaborative screen building
+ *  3. Registers window-relative bounds with the SDK so touches are
+ *     auto-classified as content (inside) vs fixed UI (outside)
+ *
+ * @param forwardedRef  The consumer's ref (function or object).
+ * @param userHandlers  The consumer's own scroll/layout handlers — always
+ *                      called after the SDK's.
+ */
+export function useRepliqoScrollTracking(
+  forwardedRef: React.Ref<unknown>,
+  userHandlers: ForwardedHandlers,
+): RepliqoScrollHandlers {
+  const debounceTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const scrollIntervalTimer = useRef<ReturnType<typeof setInterval> | null>(null);
+  const initialLayoutTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const lastCaptureTime = useRef(0);
+  const lastCaptureY = useRef(-999);
+  const lastMeasureTime = useRef(0);
+  const lastScrollEventAt = useRef(0);
+  const initialCaptured = useRef(false);
+  const realContentHeight = useRef(0);
+  const scrollViewId = useRef<string>(nextScrollViewId());
+  const innerRef = useRef<unknown>(null);
+  const isMounted = useRef(true);
+  // Last measured window-relative top Y — passed to captureScrollTile so
+  // the backend can crop each tile to just the scroll viewport area.
+  const lastViewportTop = useRef<number | null>(null);
+  const scrollState = useRef<{
+    offsetY: number;
+    viewportHeight: number;
+    contentHeight: number;
+  } | null>(null);
+
+  // Keep the latest user handlers in a ref so our stable callbacks always
+  // call the current ones.
+  const handlersRef = useRef(userHandlers);
+  handlersRef.current = userHandlers;
+
+  // Forward the inner ref to the consumer's ref (if provided).
+  // IMPORTANT: do NOT clear innerRef on cleanup — RN sometimes calls the
+  // ref callback with null mid-update, and clearing would break async
+  // measurement callbacks that fire after the ref reattaches.
+  const setRef = useCallback(
+    (node: unknown) => {
+      if (node !== null) {
+        innerRef.current = node;
+      }
+      if (typeof forwardedRef === 'function') {
+        forwardedRef(node);
+      } else if (forwardedRef) {
+        (forwardedRef as React.MutableRefObject<unknown>).current = node;
+      }
+    },
+    [forwardedRef],
+  );
+
+  /**
+   * Resolve the node that actually supports measureInWindow. FlatList (and
+   * other VirtualizedList wrappers) don't expose it directly — their inner
+   * ScrollView does, reachable via getNativeScrollRef().
+   */
+  const resolveMeasurableNode = (): any => {
+    const node: any = innerRef.current;
+    if (!node) return null;
+    if (typeof node.measureInWindow === 'function') return node;
+    try {
+      const inner =
+        typeof node.getNativeScrollRef === 'function'
+          ? node.getNativeScrollRef()
+          : typeof node.getScrollableNode === 'function'
+            ? node.getScrollableNode()
+            : null;
+      if (inner && typeof inner.measureInWindow === 'function') return inner;
+    } catch {
+      /* ignore */
+    }
+    return null;
+  };
+
+  /**
+   * Measure window-relative bounds and register with the SDK.
+   * Idempotent + safe to call after unmount (guards via isMounted).
+   */
+  const measureAndRegister = useCallback(() => {
+    if (!isMounted.current) return;
+    const node = resolveMeasurableNode();
+    if (!node) return;
+    node.measureInWindow((x: number, y: number, width: number, height: number) => {
+      if (!isMounted.current) return;
+      // RN sometimes returns 0/0 dims before the view is positioned —
+      // ignore those, the next onLayout/onScroll will re-measure.
+      if (width <= 0 || height <= 0) return;
+      lastViewportTop.current = y;
+      try {
+        AppAnalytics.getInstance().registerScrollView(scrollViewId.current, {
+          x, y, width, height,
+        });
+      } catch {}
+    });
+  }, []);
+
+  // Cleanup all timers + unregister + listeners on unmount
+  useEffect(() => {
+    const id = scrollViewId.current;
+    isMounted.current = true;
+
+    // Re-measure when keyboard appears/disappears (causes layout shift)
+    const showSub = Keyboard.addListener('keyboardDidShow', measureAndRegister);
+    const hideSub = Keyboard.addListener('keyboardDidHide', measureAndRegister);
+
+    return () => {
+      isMounted.current = false;
+      if (debounceTimer.current) clearTimeout(debounceTimer.current);
+      if (scrollIntervalTimer.current) clearInterval(scrollIntervalTimer.current);
+      if (initialLayoutTimer.current) clearTimeout(initialLayoutTimer.current);
+      showSub.remove();
+      hideSub.remove();
+      try {
+        AppAnalytics.getInstance().unregisterScrollView(id);
+      } catch {}
+    };
+  }, [measureAndRegister]);
+
+  /**
+   * Core tile capture logic. Reads from refs (stable across renders).
+   * Checks throttle + delta before capturing.
+   *
+   * @param force Skip throttle check (used for interval captures)
+   */
+  const doCapture = (force = false) => {
+    if (!isMounted.current) return;
+    const state = scrollState.current;
+    if (!state || state.viewportHeight <= 0) return;
+
+    const now = Date.now();
+    if (!force && now - lastCaptureTime.current < THROTTLE_MS) return;
+
+    // Always check delta — no point re-capturing the same position
+    if (
+      Math.abs(state.offsetY - lastCaptureY.current) < MIN_DELTA_PX &&
+      initialCaptured.current
+    )
+      return;
+
+    lastCaptureTime.current = now;
+    lastCaptureY.current = state.offsetY;
+    initialCaptured.current = true;
+
+    try {
+      const windowHeight = Dimensions.get('window').height;
+      AppAnalytics.getInstance().captureScrollTile(
+        state.offsetY,
+        state.viewportHeight,
+        state.contentHeight,
+        lastViewportTop.current ?? undefined,
+        windowHeight,
+      );
+    } catch {}
+  };
+
+  /** Stop the continuous-scroll interval timer. */
+  const stopScrollInterval = () => {
+    if (scrollIntervalTimer.current !== null) {
+      clearInterval(scrollIntervalTimer.current);
+      scrollIntervalTimer.current = null;
+    }
+  };
+
+  /**
+   * Start the interval timer for continuous scroll captures. Self-stops
+   * when scroll events stop arriving (programmatic scrolls never fire the
+   * drag/momentum end events that would stop it otherwise).
+   */
+  const startScrollInterval = () => {
+    if (scrollIntervalTimer.current !== null) return;
+    scrollIntervalTimer.current = setInterval(() => {
+      if (Date.now() - lastScrollEventAt.current > INTERVAL_IDLE_STOP_MS) {
+        stopScrollInterval();
+        return;
+      }
+      doCapture(true); // force=true skips throttle
+    }, SCROLL_INTERVAL_MS);
+  };
+
+  const onScroll = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      const { contentOffset, layoutMeasurement, contentSize } =
+        event.nativeEvent;
+
+      lastScrollEventAt.current = Date.now();
+
+      // Update SDK with current scroll offset (both legacy + new registry)
+      try {
+        const sdk = AppAnalytics.getInstance();
+        sdk.setScrollOffset(contentOffset.y);
+        sdk.updateScrollViewOffset(scrollViewId.current, contentOffset.y);
+      } catch {}
+
+      // Re-measure bounds occasionally during scroll — catches layout
+      // shifts from animations, keyboard, orientation changes, etc.
+      const now = Date.now();
+      if (now - lastMeasureTime.current > REMEASURE_THROTTLE_MS) {
+        lastMeasureTime.current = now;
+        measureAndRegister();
+      }
+
+      // Update scroll state — use realContentHeight if available
+      const bestContentHeight =
+        realContentHeight.current > 0
+          ? realContentHeight.current
+          : contentSize.height;
+      scrollState.current = {
+        offsetY: contentOffset.y,
+        viewportHeight: layoutMeasurement.height,
+        contentHeight: bestContentHeight,
+      };
+
+      // Debounce: capture after scroll stops
+      if (debounceTimer.current) clearTimeout(debounceTimer.current);
+      debounceTimer.current = setTimeout(() => doCapture(), DEBOUNCE_MS);
+
+      // Start interval for continuous scroll captures
+      startScrollInterval();
+
+      // Capture initial tile (Y~0) on first scroll event with real dims
+      if (!initialCaptured.current && contentOffset.y < 10) {
+        if (initialLayoutTimer.current) clearTimeout(initialLayoutTimer.current);
+        initialLayoutTimer.current = setTimeout(() => doCapture(), 200);
+      }
+
+      handlersRef.current.onScroll?.(event);
+    },
+    [measureAndRegister],
+  );
+
+  const onScrollEndDrag = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      // User lifted finger — capture immediately
+      stopScrollInterval();
+      doCapture(true);
+      handlersRef.current.onScrollEndDrag?.(event);
+    },
+    [],
+  );
+
+  const onMomentumScrollEnd = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      if (debounceTimer.current) {
+        clearTimeout(debounceTimer.current);
+        debounceTimer.current = null;
+      }
+      stopScrollInterval();
+      doCapture(true);
+      handlersRef.current.onMomentumScrollEnd?.(event);
+    },
+    [],
+  );
+
+  const onLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      const { height } = event.nativeEvent.layout;
+      if (!initialCaptured.current && height > 0) {
+        scrollState.current = {
+          offsetY: 0,
+          viewportHeight: height,
+          contentHeight: realContentHeight.current || height,
+        };
+        // Clear any prior pending initial-capture timer before scheduling
+        if (initialLayoutTimer.current) clearTimeout(initialLayoutTimer.current);
+        initialLayoutTimer.current = setTimeout(() => doCapture(), 1000);
+      }
+      // Register window-relative bounds immediately (no setTimeout).
+      // measureInWindow itself is async; if it returns 0/0 dims, the
+      // next onLayout / onScroll will retry — no race window.
+      measureAndRegister();
+      handlersRef.current.onLayout?.(event);
+    },
+    [measureAndRegister],
+  );
+
+  /**
+   * Track the real content height from onContentSizeChange.
+   * This is more reliable than the first scroll event and ensures
+   * the initial tile at Y=0 has correct contentHeight metadata.
+   */
+  const onContentSizeChange = useCallback((w: number, h: number) => {
+    realContentHeight.current = h;
+    // Update scroll state if it exists
+    if (scrollState.current) {
+      scrollState.current.contentHeight = h;
+    }
+    handlersRef.current.onContentSizeChange?.(w, h);
+  }, []);
+
+  return {
+    setRef,
+    onScroll,
+    onScrollEndDrag,
+    onMomentumScrollEnd,
+    onLayout,
+    onContentSizeChange,
+  };
+}