feat: add debug prop

Author: johnhaup

example/app/scrollviews/vertical.tsx

@@ -18,6 +18,7 @@ export default function VerticalScrollView() {
         ref={ref}
         offset={OFFSET}
         showsVerticalScrollIndicator={false}
+        debug
       >
         <Blocks />
       </LazyScrollView>

example/components/blocks/Blocks.tsx

@@ -29,6 +29,7 @@ export function Blocks({ horizontal }: { horizontal?: boolean }) {
           <FireOnceBlock
             key={`fire-once-child-${index}`}
             percentVisibleThreshold={1}
+            debug
           />
         );
       }
@@ -38,6 +39,7 @@ export function Blocks({ horizontal }: { horizontal?: boolean }) {
           key={`${source.toString()}-${index}`}
           source={source}
           percentVisibleThreshold={1}
+          debug
         />
       );
     },

src/components/LazyChild/LazyChild.tsx

@@ -12,6 +12,7 @@ export const LazyChild = function (props: LazyChildProps) {
       <BareLazyChild
         onEnterThresholdPass={props.onEnterThresholdPass}
         onVisibilityEnter={props.onVisibilityEnter}
+        debug={props.debug}
       >
         {props.children}
       </BareLazyChild>

src/components/LazyChild/components/BareLazyChild.tsx

@@ -1,13 +1,15 @@
 import React, { useEffect, useRef } from 'react';
 import { LazyChildProps } from '../types';
+import { logger } from '../../../utils/logger';
 
 export function BareLazyChild({
   children,
   onEnterThresholdPass,
   onVisibilityEnter,
+  debug = false,
 }: Pick<
   LazyChildProps,
-  'children' | 'onEnterThresholdPass' | 'onVisibilityEnter'
+  'children' | 'onEnterThresholdPass' | 'onVisibilityEnter' | 'debug'
 >) {
   const _hasFired = useRef(false);
 
@@ -17,11 +19,19 @@ export function BareLazyChild({
       if (typeof onEnterThresholdPass === 'function') {
         onEnterThresholdPass();
       }
+
       if (typeof onVisibilityEnter === 'function') {
         onVisibilityEnter();
       }
+
+      if (debug) {
+        logger.log(
+          '<LazyChild>',
+          'No LazyScrollView provider found. Firing onEnterThresholdPass and onVisibilityEnter once.'
+        );
+      }
     }
-  }, [onEnterThresholdPass, onVisibilityEnter]);
+  }, [debug, onEnterThresholdPass, onVisibilityEnter]);
 
   return <>{children}</>;
 }

src/components/LazyChild/components/FullLazyChild.tsx

@@ -2,6 +2,7 @@ import React, { useCallback } from 'react';
 import { Dimensions, type LayoutChangeEvent } from 'react-native';
 import Animated, {
   measure,
+  runOnJS,
   runOnUI,
   useAnimatedReaction,
   useAnimatedRef,
@@ -12,16 +13,22 @@ import { useAnimatedContext } from '../../../context/AnimatedContext';
 import { useEnteringCallbacks } from '../hooks/useEnteringCallbacks';
 import { useVisibilityCallbacks } from '../hooks/useVisibilityCallbacks';
 import { LazyChildProps } from '../types';
+import { logger } from '../../../utils/logger';
 
 const SCREEN_HEIGHT = Dimensions.get('window').height;
 
+const log = (...args: Parameters<typeof console.log>) => {
+  logger.log('<LazyChild>', ...args);
+};
+
 export function FullLazyChild({
   children,
   onEnterThresholdPass,
   onExitThresholdPass,
   percentVisibleThreshold = 1,
   onVisibilityEnter,
   onVisibilityExit,
+  debug = false,
 }: LazyChildProps) {
   const {
     startTrigger,
@@ -45,6 +52,8 @@ export function FullLazyChild({
    */
   const _measurement = useSharedValue<ReturnType<typeof measure>>(null);
 
+  const _debug = useSharedValue(debug);
+
   const _shouldFireThresholdEnter = useSharedValue(
     typeof onEnterThresholdPass === 'function'
   );
@@ -70,6 +79,10 @@ export function FullLazyChild({
     'worklet';
     const measurement = measure(_viewRef);
 
+    if (_debug.value) {
+      runOnJS(log)('measurement:', measurement);
+    }
+
     if (measurement && (measurement?.height || measurement?.width)) {
       _measurement.value = measurement;
     }
@@ -85,6 +98,10 @@ export function FullLazyChild({
       );
     },
     (shouldMeasure) => {
+      if (_debug.value) {
+        runOnJS(log)('shouldMeasure:', shouldMeasure);
+      }
+
       if (shouldMeasure) {
         measureView();
       }

src/components/LazyChild/types.ts

@@ -31,4 +31,8 @@ export interface LazyChildProps extends LazyChildCallbacks {
    * @defaultValue 1.0
    */
   percentVisibleThreshold?: number;
+  /**
+   * When true, console.logs LazyChilds measurement data.  Even if true, will not call console.log in production.
+   */
+  debug?: boolean;
 }

src/components/LazyScrollView.tsx

@@ -14,13 +14,19 @@ import {
 } from 'react-native';
 import Animated, {
   measure,
+  runOnJS,
   runOnUI,
   useAnimatedRef,
   useDerivedValue,
   useScrollViewOffset,
   useSharedValue,
 } from 'react-native-reanimated';
 import { AnimatedContext } from '../context/AnimatedContext';
+import { logger } from '../utils/logger';
+
+const log = (...args: Parameters<typeof console.log>) => {
+  logger.log('<LazyScrollView>', ...args);
+};
 
 export interface LazyScrollViewMethods {
   scrollTo: typeof ScrollView.prototype.scrollTo;
@@ -38,6 +44,10 @@ export interface LazyScrollViewProps {
    * Ref to the LazyScrollView.  Exposes scrollTo, scrollToStart, and scrollToEnd methods.
    */
   ref?: MutableRefObject<LazyScrollViewMethods>;
+  /**
+   * When true, console.logs scrollview measurements.  Even if true, will not call console.log in production.
+   */
+  debug?: boolean;
 }
 
 type Props = LazyScrollViewProps &
@@ -50,14 +60,15 @@ type Props = LazyScrollViewProps &
  * ScrollView to wrap Lazy Children in.
  */
 const LazyScrollView = forwardRef<LazyScrollViewMethods, Props>(
-  ({ children, offset: injectedOffset, ...rest }, ref) => {
+  ({ children, offset: injectedOffset, debug = false, ...rest }, ref) => {
     const _scrollRef = useAnimatedRef<Animated.ScrollView>();
     const _wrapperRef = useRef<View>(null);
     const _offset = useSharedValue(injectedOffset || 0);
     const _containerDimensions = useSharedValue({ width: 0, height: 0 });
     const _containerCoordinates = useSharedValue({ x: 0, y: 0 });
     const _contentDimensions = useSharedValue({ width: 0, height: 0 });
     const _statusBarHeight = useSharedValue(StatusBar.currentHeight || 0);
+    const _debug = useSharedValue(debug);
     const horizontal = useSharedValue(!!rest.horizontal);
 
     useImperativeHandle(ref, () => ({
@@ -107,17 +118,30 @@ const LazyScrollView = forwardRef<LazyScrollViewMethods, Props>(
           width: e.nativeEvent.layout.width,
         };
 
+        if (debug) {
+          log('dimensions:', {
+            height: _containerDimensions.value.height,
+            width: _containerDimensions.value.width,
+          });
+        }
+
         // onLayout runs when RN finishes render, but native layout may not be fully settled until the next frame.
         requestAnimationFrame(() => {
           runOnUI(() => {
             'worklet';
             const measurement = measure(_scrollRef);
 
             if (measurement) {
-              _containerCoordinates.value = {
+              const coordinates = {
                 x: measurement.pageX,
                 y: measurement.pageY + _statusBarHeight.value,
               };
+
+              if (_debug.value) {
+                runOnJS(log)('coordinates:', coordinates);
+              }
+
+              _containerCoordinates.value = coordinates;
             }
           })();
         });
@@ -128,10 +152,16 @@ const LazyScrollView = forwardRef<LazyScrollViewMethods, Props>(
 
     const measureContent = useCallback(
       (e: LayoutChangeEvent) => {
-        _contentDimensions.value = {
+        const dimensions = {
           height: e.nativeEvent.layout.height,
           width: e.nativeEvent.layout.width,
         };
+
+        if (debug) {
+          log('content dimensions:', dimensions);
+        }
+
+        _contentDimensions.value = dimensions;
       },
       // eslint-disable-next-line react-hooks/exhaustive-deps -- shared values do not trigger re-renders
       []

src/utils/logger.ts

@@ -0,0 +1,9 @@
+export const log = (TAG: string, ...args: Parameters<typeof console.log>) => {
+  if (__DEV__) {
+    console.log('[LazyScrollView]', TAG, ...args);
+  }
+};
+
+export const logger = {
+  log,
+};