react-native-lumen 1.0.0 → 1.1.0

package/src/components/TourZone.tsx

@@ -1,7 +1,7 @@
 import React, {
   useEffect,
   useCallback,
-  useRef,
+  useMemo,
   type ComponentType,
 } from 'react';
 import type { ViewStyle, StyleProp } from 'react-native';
@@ -16,7 +16,12 @@ import {
   useSharedValue,
 } from 'react-native-reanimated';
 import { Dimensions } from 'react-native';
-import type { InternalTourContextType } from '../types';
+import type {
+  InternalTourContextType,
+  ZoneStyle,
+  ZoneShape,
+  CardProps,
+} from '../types';
 
 const { height: SCREEN_HEIGHT } = Dimensions.get('window');
 
@@ -27,11 +32,28 @@ interface TourZoneProps {
   name?: string;
   description: string;
   order?: number;
-  shape?: 'rect' | 'circle';
+  shape?: ZoneShape;
   borderRadius?: number;
   children: React.ReactNode;
   style?: StyleProp<ViewStyle>;
   clickable?: boolean;
+  preventInteraction?: boolean;
+  required?: boolean;
+  completed?: boolean;
+  zonePadding?: number;
+  zonePaddingTop?: number;
+  zonePaddingRight?: number;
+  zonePaddingBottom?: number;
+  zonePaddingLeft?: number;
+  zoneBorderWidth?: number;
+  zoneBorderColor?: string;
+  zoneGlowColor?: string;
+  zoneGlowRadius?: number;
+  zoneGlowSpread?: number;
+  zoneGlowOffsetX?: number;
+  zoneGlowOffsetY?: number;
+  zoneStyle?: ZoneStyle;
+  renderCustomCard?: (props: CardProps) => React.ReactNode;
 }
 
 export const TourZone: React.FC<TourZoneProps> = ({
@@ -39,11 +61,28 @@ export const TourZone: React.FC<TourZoneProps> = ({
   name,
   description,
   order,
-  shape = 'rect',
+  shape = 'rounded-rect',
   borderRadius = 10,
   children,
   style,
   clickable,
+  preventInteraction,
+  required,
+  completed,
+  zonePadding,
+  zonePaddingTop,
+  zonePaddingRight,
+  zonePaddingBottom,
+  zonePaddingLeft,
+  zoneBorderWidth,
+  zoneBorderColor,
+  zoneGlowColor,
+  zoneGlowRadius,
+  zoneGlowSpread,
+  zoneGlowOffsetX,
+  zoneGlowOffsetY,
+  zoneStyle,
+  renderCustomCard,
 }) => {
   const {
     registerStep,
@@ -59,34 +98,65 @@ export const TourZone: React.FC<TourZoneProps> = ({
     targetRadius,
     config,
   } = useTour() as InternalTourContextType;
-  const viewRef = useAnimatedRef<any>();
 
+  const viewRef = useAnimatedRef<any>();
   const isActive = currentStep === stepKey;
 
-  // Track if we're currently scrolling to prevent position updates during scroll
+  // The critical lock for the UI thread
   const isScrolling = useSharedValue(false);
-  const hasScrolled = useRef(false);
 
-  // Signal when scroll completes (from JS thread)
-  const onScrollComplete = useCallback(() => {
-    isScrolling.value = false;
-  }, [isScrolling]);
+  console.log(`zoneGlowRadius ${stepKey}`, zoneGlowRadius);
+
+  const resolvedZoneStyle: ZoneStyle = useMemo(
+    () => ({
+      ...zoneStyle,
+      ...(zonePadding !== undefined && { padding: zonePadding }),
+      ...(zonePaddingTop !== undefined && { paddingTop: zonePaddingTop }),
+      ...(zonePaddingRight !== undefined && { paddingRight: zonePaddingRight }),
+      ...(zonePaddingBottom !== undefined && {
+        paddingBottom: zonePaddingBottom,
+      }),
+      ...(zonePaddingLeft !== undefined && { paddingLeft: zonePaddingLeft }),
+      ...(zoneBorderWidth !== undefined && { borderWidth: zoneBorderWidth }),
+      ...(zoneBorderColor !== undefined && { borderColor: zoneBorderColor }),
+      ...(zoneGlowColor !== undefined && { glowColor: zoneGlowColor }),
+      ...(zoneGlowRadius !== undefined && { glowRadius: zoneGlowRadius }),
+      ...(zoneGlowSpread !== undefined && { glowSpread: zoneGlowSpread }),
+      ...(zoneGlowOffsetX !== undefined && { glowOffsetX: zoneGlowOffsetX }),
+      ...(zoneGlowOffsetY !== undefined && { glowOffsetY: zoneGlowOffsetY }),
+      shape,
+      borderRadius,
+    }),
+    [
+      zoneStyle,
+      zonePadding,
+      zonePaddingTop,
+      zonePaddingRight,
+      zonePaddingBottom,
+      zonePaddingLeft,
+      zoneBorderWidth,
+      zoneBorderColor,
+      zoneGlowColor,
+      zoneGlowRadius,
+      zoneGlowSpread,
+      zoneGlowOffsetX,
+      zoneGlowOffsetY,
+      shape,
+      borderRadius,
+    ]
+  );
 
   /**
-   * UNIFIED MEASUREMENT FUNCTION (JS THREAD)
-   * Always measures relative to SCREEN (Viewport), not Content.
-   * This fixes the bug where measureLayout returned content-relative Y.
+   * Captures the final, perfect coordinates and UNLOCKS the UI thread.
+   * This is explicitly the ONLY function allowed to set isScrolling.value = false.
    */
   const measureJS = useCallback(() => {
-    if (isScrolling.value || !isActive) {
-      return;
-    }
+    if (!isActive) return;
 
     const view = viewRef.current as any;
     const container = containerRef.current as any;
 
     if (view && container) {
-      // 1. Measure the View in Screen Coordinates (PageX/PageY)
       view.measure(
         (
           _x: number,
@@ -96,8 +166,6 @@ export const TourZone: React.FC<TourZoneProps> = ({
           pageX: number,
           pageY: number
         ) => {
-          // 2. Measure the Container (TourOverlay) in Screen Coordinates
-          // This handles cases where the Tour Overlay isn't exactly at 0,0 (e.g. inside a SafeAreaView)
           container.measure(
             (
               _cx: number,
@@ -108,7 +176,6 @@ export const TourZone: React.FC<TourZoneProps> = ({
               containerPageY: number
             ) => {
               if (width > 0 && height > 0 && !isNaN(pageX) && !isNaN(pageY)) {
-                // Calculate final position relative to the Tour Overlay
                 const finalX = pageX - containerPageX;
                 const finalY = pageY - containerPageY;
 
@@ -118,89 +185,43 @@ export const TourZone: React.FC<TourZoneProps> = ({
                   width,
                   height,
                 });
+
+                // Unlock the UI thread to take over tracking
+                isScrolling.value = false;
               }
             }
           );
         }
       );
     }
-  }, [containerRef, stepKey, updateStepLayout, viewRef, isScrolling, isActive]);
-
-  // Initial measurement when step becomes active
-  useEffect(() => {
-    if (!isActive) return;
-
-    // Small delay to ensure layout is ready
-    const timeoutId = setTimeout(() => {
-      measureJS();
-    }, 50);
-
-    return () => clearTimeout(timeoutId);
-  }, [isActive, measureJS]);
-
-  // Reanimated Frame Callback (UI Thread Tracking)
-  // This keeps the highlight sticky during manual user scrolling
-  useFrameCallback(() => {
-    'worklet';
-    if (!isActive || isScrolling.value) {
-      return;
-    }
-    try {
-      const measured = measure(viewRef);
-      const container = measure(containerRef as AnimatedRef<any>);
-
-      if (measured && container) {
-        const x = measured.pageX - container.pageX;
-        const y = measured.pageY - container.pageY;
-        const width = measured.width;
-        const height = measured.height;
-
-        if (
-          width > 0 &&
-          height > 0 &&
-          !isNaN(x) &&
-          !isNaN(y) &&
-          isFinite(x) &&
-          isFinite(y)
-        ) {
-          const springConfig = config?.springConfig ?? {
-            damping: 100,
-            stiffness: 100,
-          };
-
-          targetX.value = withSpring(x, springConfig);
-          targetY.value = withSpring(y, springConfig);
-          targetWidth.value = withSpring(width, springConfig);
-          targetHeight.value = withSpring(height, springConfig);
-          targetRadius.value = withSpring(borderRadius, springConfig);
-        }
-      }
-    } catch (e) {
-      // Silently ignore measurement errors on UI thread
-    }
-  }, isActive);
+  }, [containerRef, isActive, isScrolling, stepKey, updateStepLayout, viewRef]);
 
-  // Auto-scroll Effect
+  /**
+   * Unified Pipeline: Measure -> Predict Scroll -> Scroll -> Measure Final -> Unlock
+   * Replaces all independent timers to prevent race conditions on consecutive steps.
+   */
   useEffect(() => {
     if (!isActive || !scrollViewRef?.current || !viewRef.current) {
       return;
     }
 
-    hasScrolled.current = false;
-    const view = viewRef.current as any;
-    const scroll = scrollViewRef.current as any;
-    const container = containerRef.current as any;
-
+    let cancelled = false;
     let attemptCount = 0;
-    const maxAttempts = 3;
+    const maxAttempts = 5;
+    let hasInitiatedScroll = false;
 
-    const attemptMeasurement = (delay: number) => {
-      const timeoutId = setTimeout(() => {
-        if (hasScrolled.current) return;
+    // 1. Lock immediately so the UI thread doesn't grab off-screen coordinates
+    isScrolling.value = true;
 
+    const checkAndScroll = (delay: number) => {
+      const timeoutId = setTimeout(() => {
+        if (cancelled || hasInitiatedScroll) return;
         attemptCount++;
 
-        // 1. Check current visibility on screen
+        const view = viewRef.current as any;
+        const scroll = scrollViewRef.current as any;
+        const container = containerRef.current as any;
+
         view.measure(
           (
             _mx: number,
@@ -210,21 +231,17 @@ export const TourZone: React.FC<TourZoneProps> = ({
             px: number,
             py: number
           ) => {
+            if (cancelled) return;
+
             if (mw > 0 && mh > 0 && !isNaN(px) && !isNaN(py)) {
-              const viewportHeight = SCREEN_HEIGHT;
               const topBuffer = 100;
               const bottomBuffer = 150;
-
-              // Check if element is out of the "safe" visual zone
               const needsScroll =
-                py < topBuffer || py + mh > viewportHeight - bottomBuffer;
+                py < topBuffer || py + mh > SCREEN_HEIGHT - bottomBuffer;
 
               if (needsScroll) {
-                hasScrolled.current = true;
-                isScrolling.value = true;
+                hasInitiatedScroll = true;
 
-                // 2. Measure ScrollView to get its Screen Position (Offset from top)
-                // This fixes the "upwards" bug by accounting for headers/safe-areas
                 scroll.measure(
                   (
                     _sx: number,
@@ -234,17 +251,18 @@ export const TourZone: React.FC<TourZoneProps> = ({
                     scrollPx: number,
                     scrollPy: number
                   ) => {
-                    // 3. Measure Element relative to ScrollView Content
+                    if (cancelled) return;
+
                     if (view.measureLayout) {
                       view.measureLayout(
                         scroll,
                         (contentX: number, contentY: number) => {
-                          // Calculate target scroll position (center the element)
+                          if (cancelled) return;
+
                           const centerY =
-                            contentY - viewportHeight / 2 + mh / 2 + 50;
+                            contentY - SCREEN_HEIGHT / 2 + mh / 2 + 50;
                           const scrollY = Math.max(0, centerY);
 
-                          // 4. Measure Container to map coordinates to Overlay space
                           container.measure(
                             (
                               _cx: number,
@@ -254,12 +272,12 @@ export const TourZone: React.FC<TourZoneProps> = ({
                               containerPx: number,
                               containerPy: number
                             ) => {
-                              // THE FIX: Add scrollPy (ScrollView's screen Y)
-                              // Visual Y = ScrollViewScreenY + (ElementContentY - ScrollAmount)
+                              if (cancelled) return;
+
+                              // Calculate predictive screen coordinates so the zone smoothly jumps
+                              // to the destination *while* the screen is scrolling.
                               const targetScreenY =
                                 scrollPy + contentY - scrollY - containerPy;
-
-                              // X is simpler: ScrollViewScreenX + ElementContentX - ContainerScreenX
                               const targetScreenX =
                                 scrollPx + contentX - containerPx;
 
@@ -272,70 +290,141 @@ export const TourZone: React.FC<TourZoneProps> = ({
 
                               try {
                                 scroll.scrollTo({ y: scrollY, animated: true });
-                                // Wait for scroll animation
-                                setTimeout(() => onScrollComplete(), 800);
                               } catch (e) {
                                 console.error(e);
-                                onScrollComplete();
                               }
+
+                              // Wait for the scroll animation to settle, then verify exact position
+                              setTimeout(() => {
+                                if (!cancelled) measureJS();
+                              }, 800);
                             }
                           );
+                        },
+                        () => {
+                          // Fallback if measureLayout is unavailable
+                          setTimeout(() => {
+                            if (!cancelled) measureJS();
+                          }, 800);
                         }
                       );
                     }
                   }
                 );
               } else {
-                // Element is already visible - just sync position
-                container.measure(
-                  (
-                    _cx: number,
-                    _cy: number,
-                    _cw: number,
-                    _ch: number,
-                    cPx: number,
-                    cPy: number
-                  ) => {
-                    const finalX = px - cPx;
-                    const finalY = py - cPy;
-
-                    updateStepLayout(stepKey, {
-                      x: finalX,
-                      y: finalY,
-                      width: mw,
-                      height: mh,
-                    });
-                  }
-                );
+                // No scroll needed, just get the perfect coordinates and unlock
+                measureJS();
               }
             } else if (attemptCount < maxAttempts) {
-              attemptMeasurement(150 * attemptCount);
+              checkAndScroll(150);
             }
           }
         );
       }, delay);
+
       return timeoutId;
     };
 
-    const timeoutId = attemptMeasurement(150);
-    return () => clearTimeout(timeoutId);
+    const initialTimeout = checkAndScroll(50);
+
+    return () => {
+      cancelled = true;
+      clearTimeout(initialTimeout);
+    };
   }, [
     isActive,
     scrollViewRef,
     viewRef,
-    stepKey,
-    isScrolling,
-    onScrollComplete,
     containerRef,
+    stepKey,
     updateStepLayout,
+    measureJS,
+    isScrolling,
   ]);
 
-  // Standard onLayout handler (uses the unified measureJS)
-  const onLayout = () => {
-    measureJS();
-  };
+  // UI Thread tracking
+  useFrameCallback(() => {
+    'worklet';
+    if (!isActive || isScrolling.value) {
+      return;
+    }
+    try {
+      const measured = measure(viewRef);
+      const container = measure(containerRef as AnimatedRef<any>);
+
+      if (measured && container) {
+        const x = measured.pageX - container.pageX;
+        const y = measured.pageY - container.pageY;
+        const width = measured.width;
+        const height = measured.height;
+
+        if (
+          width > 0 &&
+          height > 0 &&
+          !isNaN(x) &&
+          !isNaN(y) &&
+          isFinite(x) &&
+          isFinite(y)
+        ) {
+          const springConfig = config?.springConfig ?? {
+            damping: 100,
+            stiffness: 100,
+          };
+
+          const zpt =
+            resolvedZoneStyle.paddingTop ?? resolvedZoneStyle.padding ?? 0;
+          const zpr =
+            resolvedZoneStyle.paddingRight ?? resolvedZoneStyle.padding ?? 0;
+          const zpb =
+            resolvedZoneStyle.paddingBottom ?? resolvedZoneStyle.padding ?? 0;
+          const zpl =
+            resolvedZoneStyle.paddingLeft ?? resolvedZoneStyle.padding ?? 0;
+          const zShape = resolvedZoneStyle.shape ?? 'rounded-rect';
+
+          let sx = x - zpl;
+          let sy = y - zpt;
+          let sw = width + zpl + zpr;
+          let sh = height + zpt + zpb;
+          let sr = borderRadius;
+
+          if (zShape === 'circle') {
+            const cx = x + width / 2;
+            const cy = y + height / 2;
+            const radius =
+              Math.max(width, height) / 2 + (resolvedZoneStyle.padding ?? 0);
+            sx = cx - radius;
+            sy = cy - radius;
+            sw = radius * 2;
+            sh = radius * 2;
+            sr = radius;
+          } else if (zShape === 'pill') {
+            sx = x - zpl;
+            sy = y - zpt;
+            sw = width + zpl + zpr;
+            sh = height + zpt + zpb;
+            sr = sh / 2;
+          }
+
+          targetX.value = withSpring(sx, springConfig);
+          targetY.value = withSpring(sy, springConfig);
+          targetWidth.value = withSpring(sw, springConfig);
+          targetHeight.value = withSpring(sh, springConfig);
+          targetRadius.value = withSpring(sr, springConfig);
+        }
+      }
+    } catch {
+      // Silently ignore measurement errors on UI thread
+    }
+  }, isActive);
+
+  // Sync position if the element physically resizes, but strictly avoid
+  // measuring if we are currently handling an orchestrated scroll.
+  const onLayout = useCallback(() => {
+    if (isActive && !isScrolling.value) {
+      measureJS();
+    }
+  }, [isActive, isScrolling.value, measureJS]);
 
-  // Register step on mount
   useEffect(() => {
     registerStep({
       key: stepKey,
@@ -343,7 +432,12 @@ export const TourZone: React.FC<TourZoneProps> = ({
       description,
       order,
       clickable,
-      meta: { shape, borderRadius },
+      preventInteraction,
+      required,
+      completed,
+      meta: { shape: resolvedZoneStyle.shape, borderRadius },
+      zoneStyle: resolvedZoneStyle,
+      renderCustomCard,
     });
     return () => unregisterStep(stepKey);
   }, [
@@ -351,12 +445,15 @@ export const TourZone: React.FC<TourZoneProps> = ({
     name,
     description,
     order,
-    shape,
     borderRadius,
     registerStep,
-    registerStep,
     unregisterStep,
     clickable,
+    preventInteraction,
+    required,
+    completed,
+    resolvedZoneStyle,
+    renderCustomCard,
   ]);
 
   return (

package/src/constants/defaults.ts

@@ -1,4 +1,5 @@
 import type { WithSpringConfig } from 'react-native-reanimated';
+import type { ZoneStyle } from '../types';
 
 export const DEFAULT_SPRING_CONFIG: WithSpringConfig = {
   damping: 20,
@@ -13,3 +14,53 @@ export const DEFAULT_LABELS = {
   finish: 'Finish',
   skip: 'Skip',
 };
+
+/**
+ * Default zone style configuration.
+ * These values are used when no custom style is provided.
+ */
+export const DEFAULT_ZONE_STYLE: Required<ZoneStyle> = {
+  padding: 0,
+  paddingTop: 0,
+  paddingRight: 0,
+  paddingBottom: 0,
+  paddingLeft: 0,
+  borderRadius: 10,
+  shape: 'rounded-rect',
+  borderWidth: 0,
+  borderColor: 'transparent',
+  glowColor: '#FFFFFF',
+  glowRadius: 10,
+  glowSpread: 5,
+  glowOffsetX: 0,
+  glowOffsetY: 0,
+  springDamping: 20,
+  springStiffness: 90,
+};
+
+/**
+ * Merges global and per-step zone styles with defaults.
+ */
+export function resolveZoneStyle(
+  globalStyle?: ZoneStyle,
+  stepStyle?: ZoneStyle
+): Required<ZoneStyle> {
+  const merged = {
+    ...DEFAULT_ZONE_STYLE,
+    ...globalStyle,
+    ...stepStyle,
+  };
+
+  // Handle individual padding overrides
+  return {
+    ...merged,
+    paddingTop:
+      stepStyle?.paddingTop ?? globalStyle?.paddingTop ?? merged.padding,
+    paddingRight:
+      stepStyle?.paddingRight ?? globalStyle?.paddingRight ?? merged.padding,
+    paddingBottom:
+      stepStyle?.paddingBottom ?? globalStyle?.paddingBottom ?? merged.padding,
+    paddingLeft:
+      stepStyle?.paddingLeft ?? globalStyle?.paddingLeft ?? merged.padding,
+  };
+}

package/src/context/TourContext.ts

@@ -0,0 +1,4 @@
+import { createContext } from 'react';
+import type { InternalTourContextType } from '../types';
+
+export const TourContext = createContext<InternalTourContextType | null>(null);

package/src/hooks/useTour.ts

@@ -1,5 +1,5 @@
 import { useContext } from 'react';
-import { TourContext } from '../components/TourProvider';
+import { TourContext } from '../context/TourContext';
 
 export const useTour = () => {
   const context = useContext(TourContext);