react-native-lumen 1.0.0

package/src/components/TourProvider.tsx

@@ -0,0 +1,361 @@
+import React, {
+  createContext,
+  useState,
+  useCallback,
+  useMemo,
+  useRef,
+  type ComponentType,
+} from 'react';
+import {
+  useSharedValue,
+  withSpring,
+  withTiming,
+  useAnimatedRef,
+  default as Animated,
+} from 'react-native-reanimated';
+import { StyleSheet } from 'react-native';
+import type {
+  TourStep,
+  MeasureResult,
+  TourConfig,
+  InternalTourContextType,
+} from '../types';
+import { TourOverlay } from './TourOverlay';
+import { TourTooltip } from './TourTooltip';
+import {
+  DEFAULT_BACKDROP_OPACITY,
+  DEFAULT_SPRING_CONFIG,
+} from '../constants/defaults';
+
+export const TourContext = createContext<InternalTourContextType | null>(null);
+
+interface TourProviderProps {
+  children: React.ReactNode;
+  /**
+   * Optional custom steps order. If provided, the tour will follow this array of keys.
+   */
+  stepsOrder?: string[];
+  /**
+   * Initial overlay opacity. Default 0.5
+   */
+  backdropOpacity?: number;
+  /**
+   * Global configuration for the tour.
+   */
+  config?: TourConfig;
+}
+
+const AnimatedView = Animated.View as unknown as ComponentType<any>;
+
+export const TourProvider: React.FC<TourProviderProps> = ({
+  children,
+  stepsOrder: initialStepsOrder,
+  backdropOpacity = DEFAULT_BACKDROP_OPACITY,
+  config,
+}) => {
+  const [steps, setSteps] = useState<Record<string, TourStep>>({});
+  const [currentStep, setCurrentStep] = useState<string | null>(null);
+
+  // ref to access latest measurements without causing re-renders
+  const measurements = useRef<Record<string, MeasureResult>>({});
+  const containerRef = useAnimatedRef<any>();
+
+  // --- Shared Values for Animations (Zero Bridge Crossing) ---
+  // Initialize off-screen or 0
+  const targetX = useSharedValue(0);
+  const targetY = useSharedValue(0);
+  const targetWidth = useSharedValue(0);
+  const targetHeight = useSharedValue(0);
+  const targetRadius = useSharedValue(10); // Default border radius
+  const opacity = useSharedValue(0); // 0 = hidden, 1 = visible
+
+  // Helper to animate to a specific step's layout
+  const animateToStep = useCallback(
+    (stepKey: string) => {
+      const measure = measurements.current[stepKey];
+      if (measure) {
+        // Validate measurements before animating
+        if (
+          !measure.width ||
+          !measure.height ||
+          measure.width <= 0 ||
+          measure.height <= 0 ||
+          isNaN(measure.x) ||
+          isNaN(measure.y) ||
+          isNaN(measure.width) ||
+          isNaN(measure.height)
+        ) {
+          console.warn(
+            '[TourProvider] Invalid measurements for step:',
+            stepKey,
+            measure
+          );
+          return;
+        }
+
+        const springConfig = config?.springConfig ?? DEFAULT_SPRING_CONFIG;
+
+        targetX.value = withSpring(measure.x, springConfig);
+        targetY.value = withSpring(measure.y, springConfig);
+        targetWidth.value = withSpring(measure.width, springConfig);
+        targetHeight.value = withSpring(measure.height, springConfig);
+
+        // If measure result has radius or step meta has radius, use it.
+        // For now defaulting to 10 or meta reading if we passed it back in measure?
+        // Let's assume meta is in steps state.
+        const step = steps[stepKey];
+        const radius = step?.meta?.borderRadius ?? 10;
+        targetRadius.value = withSpring(radius, springConfig);
+
+        // Ensure overlay is visible
+        opacity.value = withTiming(backdropOpacity, { duration: 300 });
+      } else {
+        console.warn('[TourProvider] No measurements found for step:', stepKey);
+      }
+    },
+    [
+      backdropOpacity,
+      targetX,
+      targetY,
+      targetWidth,
+      targetHeight,
+      targetRadius,
+      opacity,
+      config?.springConfig,
+      steps,
+    ]
+  );
+
+  const registerStep = useCallback((step: TourStep) => {
+    setSteps((prev) => ({ ...prev, [step.key]: step }));
+  }, []);
+
+  const unregisterStep = useCallback((key: string) => {
+    setSteps((prev) => {
+      const newSteps = { ...prev };
+      delete newSteps[key];
+      return newSteps;
+    });
+  }, []);
+
+  const updateStepLayout = useCallback(
+    (key: string, measure: MeasureResult) => {
+      // Validate measurements before storing
+      if (
+        !measure.width ||
+        !measure.height ||
+        measure.width <= 0 ||
+        measure.height <= 0 ||
+        isNaN(measure.x) ||
+        isNaN(measure.y) ||
+        isNaN(measure.width) ||
+        isNaN(measure.height) ||
+        !isFinite(measure.x) ||
+        !isFinite(measure.y) ||
+        !isFinite(measure.width) ||
+        !isFinite(measure.height)
+      ) {
+        console.warn(
+          '[TourProvider] Invalid measurement update for step:',
+          key,
+          measure
+        );
+        return;
+      }
+
+      measurements.current[key] = measure;
+      // If this step is currently active (e.g. scroll happened or resize), update shared values on the fly
+      if (currentStep === key) {
+        const springConfig = config?.springConfig ?? DEFAULT_SPRING_CONFIG;
+
+        targetX.value = withSpring(measure.x, springConfig);
+        targetY.value = withSpring(measure.y, springConfig);
+        targetWidth.value = withSpring(measure.width, springConfig);
+        targetHeight.value = withSpring(measure.height, springConfig);
+
+        // Update radius if available
+        const step = steps[key];
+        const radius = step?.meta?.borderRadius ?? 10;
+        targetRadius.value = withSpring(radius, springConfig);
+
+        // Ensure overlay is visible (fixes race condition where start() was called before measure)
+        opacity.value = withTiming(backdropOpacity, { duration: 300 });
+      }
+    },
+    [
+      currentStep,
+      targetX,
+      targetY,
+      targetWidth,
+      targetHeight,
+      targetRadius,
+      opacity,
+      backdropOpacity,
+      config?.springConfig,
+      steps,
+    ]
+  );
+
+  const getOrderedSteps = useCallback(() => {
+    if (initialStepsOrder) return initialStepsOrder;
+    // If order property exists on steps, sort by it.
+    const stepKeys = Object.keys(steps);
+    if (stepKeys.length > 0) {
+      // Check if any step has order
+      const hasOrder = stepKeys.some(
+        (key) => typeof steps[key]?.order === 'number'
+      );
+      if (hasOrder) {
+        return stepKeys.sort(
+          (a, b) => (steps[a]?.order ?? 0) - (steps[b]?.order ?? 0)
+        );
+      }
+    }
+    return stepKeys;
+  }, [initialStepsOrder, steps]);
+
+  const start = useCallback(
+    (stepKey?: string) => {
+      const ordered = getOrderedSteps();
+      const firstStep = stepKey || ordered[0];
+      if (firstStep) {
+        setCurrentStep(firstStep);
+        // We need to wait for layout if it's not ready?
+        // Assuming layout is ready since components are mounted.
+        // But if we start immediately on mount, might be tricky.
+        // For now assume standard flow.
+        // requestAnimationFrame to ensure state update propagates if needed,
+        // but simple call is usually fine.
+        setTimeout(() => animateToStep(firstStep), 0);
+      }
+    },
+    [getOrderedSteps, animateToStep]
+  );
+
+  const stop = useCallback(() => {
+    setCurrentStep(null);
+    opacity.value = withTiming(0, { duration: 300 });
+  }, [opacity]);
+
+  const next = useCallback(() => {
+    if (!currentStep) return;
+    const ordered = getOrderedSteps();
+    const currentIndex = ordered.indexOf(currentStep);
+    if (currentIndex < ordered.length - 1) {
+      const nextStep = ordered[currentIndex + 1];
+      if (nextStep) {
+        setCurrentStep(nextStep);
+        // Don't call animateToStep here - it uses cached measurements that may be stale
+        // after scroll. The useFrameCallback in TourZone will handle position tracking
+        // using measure() with correct screen coordinates (pageX/pageY).
+        // Just ensure the overlay is visible.
+        opacity.value = withTiming(backdropOpacity, { duration: 300 });
+      } else {
+        stop();
+      }
+    } else {
+      stop(); // End of tour
+    }
+  }, [currentStep, getOrderedSteps, stop, opacity, backdropOpacity]);
+
+  const prev = useCallback(() => {
+    if (!currentStep) return;
+    const ordered = getOrderedSteps();
+    const currentIndex = ordered.indexOf(currentStep);
+    if (currentIndex > 0) {
+      const prevStep = ordered[currentIndex - 1];
+      if (prevStep) {
+        setCurrentStep(prevStep);
+        // Don't call animateToStep - let useFrameCallback handle position tracking
+        opacity.value = withTiming(backdropOpacity, { duration: 300 });
+      }
+    }
+  }, [currentStep, getOrderedSteps, opacity, backdropOpacity]);
+
+  const scrollViewRef = useAnimatedRef<any>();
+
+  const setScrollViewRef = useCallback((_ref: any) => {
+    // If user passes a ref, we might want to sync it?
+    // Or we just provide this function for them to give us the ref.
+    // With useAnimatedRef, we can assign it if it's a function or object?
+    // Actually, safest is to let them assign our ref to their component.
+    // But they might have their own ref.
+    // Let's assume they call this with their ref.
+    // BUT useAnimatedRef cannot easily accept an external ref object to "become".
+    // Pattern: They should use the ref we give them, OR we wrap their component?
+    // Simpler: We just expose 'scrollViewRef' from context, and they attach it.
+    // So 'setScrollViewRef' might be redundant if we just say "here is the ref, use it".
+    // But if they have their own, they can't usage two refs easily without merging.
+    // Let's stick to exposing `scrollViewRef` from context that they MUST use.
+    // But wait, the interface says `setScrollViewRef`.
+    // Let's keep `setScrollViewRef` as a no-op or a way to manually set it if needed (not RecAnimated friendly).
+    // Actually, let's just expose `scrollViewRef` and `registerScrollView` which essentially does nothing if we expect them to use the ref object.
+    // Let's make `setScrollViewRef` actually do something if possible, or just document "Use exposed scrollViewRef".
+    // For now, let's just return the `scrollViewRef` we created.
+  }, []);
+
+  const value = useMemo<InternalTourContextType>(
+    () => ({
+      start,
+      stop,
+      next,
+      prev,
+      registerStep,
+      unregisterStep,
+      updateStepLayout,
+      currentStep,
+      targetX,
+      targetY,
+      targetWidth,
+      targetHeight,
+      targetRadius,
+      opacity,
+      steps,
+      config,
+      containerRef,
+      scrollViewRef,
+      setScrollViewRef,
+    }),
+    [
+      start,
+      stop,
+      next,
+      prev,
+      registerStep,
+      unregisterStep,
+      updateStepLayout,
+      currentStep,
+      targetX,
+      targetY,
+      targetWidth,
+      targetHeight,
+      targetRadius,
+      opacity,
+      steps,
+      config,
+      // containerRef is stable
+      scrollViewRef,
+      setScrollViewRef,
+    ]
+  );
+
+  return (
+    <TourContext.Provider value={value}>
+      <AnimatedView
+        ref={containerRef}
+        style={styles.container}
+        collapsable={false}
+      >
+        {children}
+        <TourOverlay />
+        <TourTooltip />
+      </AnimatedView>
+    </TourContext.Provider>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+});

package/src/components/TourTooltip.tsx

@@ -0,0 +1,252 @@
+import { useMemo, memo, useState, type ComponentType } from 'react';
+import {
+  StyleSheet,
+  Text,
+  View,
+  Dimensions,
+  TouchableOpacity,
+} from 'react-native';
+import Animated, {
+  useAnimatedStyle,
+  useSharedValue,
+  interpolate,
+  Extrapolation,
+} from 'react-native-reanimated';
+import { useTour } from '../hooks/useTour';
+import type { CardProps, InternalTourContextType } from '../types';
+import { DEFAULT_LABELS } from '../constants/defaults';
+
+const { width: SCREEN_WIDTH, height: SCREEN_HEIGHT } = Dimensions.get('window');
+
+export const TourTooltip = memo(() => {
+  const {
+    targetX,
+    targetY,
+    targetWidth,
+    targetHeight,
+    currentStep,
+    steps,
+    next,
+    prev,
+    stop,
+    opacity,
+    config,
+  } = useTour() as InternalTourContextType;
+
+  const currentStepData = currentStep ? steps[currentStep] : null;
+
+  const tooltipHeight = useSharedValue(150);
+  const [tooltipWidth] = useState(280);
+
+  const orderedSteps = useMemo(() => {
+    const keys = Object.keys(steps);
+    if (keys.length > 0) {
+      return keys.sort(
+        (a, b) => (steps[a]?.order ?? 0) - (steps[b]?.order ?? 0)
+      );
+    }
+    return keys;
+  }, [steps]);
+
+  const currentIndex = currentStep ? orderedSteps.indexOf(currentStep) : -1;
+  const totalSteps = orderedSteps.length;
+  const isFirst = currentIndex === 0;
+  const isLast = currentIndex === totalSteps - 1;
+
+  const tooltipStyle = useAnimatedStyle(() => {
+    'worklet';
+
+    const safeTargetX = targetX.value || 0;
+    const safeTargetY = targetY.value || 0;
+    const safeTargetWidth = Math.max(targetWidth.value || 0, 1);
+    const safeTargetHeight = Math.max(targetHeight.value || 0, 1);
+    const safeTooltipHeight = tooltipHeight.value || 150;
+
+    // FIX: Aggressive Interpolation
+    // Map the input value [0 -> 0.6] to output [0 -> 1].
+    // This ensures that even if 'opacity.value' stops at 0.7 (backdrop level),
+    // the tooltip is already fully opaque (1.0).
+    const activeOpacity = interpolate(
+      opacity.value,
+      [0, 0.6],
+      [0, 1],
+      Extrapolation.CLAMP
+    );
+
+    const spaceAbove = safeTargetY;
+    const spaceBelow = SCREEN_HEIGHT - (safeTargetY + safeTargetHeight);
+
+    const shouldPlaceAbove =
+      (spaceAbove > spaceBelow && spaceAbove > safeTooltipHeight + 30) ||
+      (safeTargetY > SCREEN_HEIGHT / 2 && spaceAbove > safeTooltipHeight + 20);
+
+    const horizontalCenter = safeTargetX + safeTargetWidth / 2;
+    const left = horizontalCenter - tooltipWidth / 2;
+
+    const clampedLeft = Math.max(
+      12,
+      Math.min(SCREEN_WIDTH - tooltipWidth - 12, left)
+    );
+
+    const style: any = {
+      position: 'absolute',
+      width: tooltipWidth,
+      left: clampedLeft,
+      opacity: activeOpacity,
+      // Add explicit background here for Reanimated to treat it as a solid block layer
+      backgroundColor: 'white',
+      transform: [{ translateY: interpolate(activeOpacity, [0, 1], [10, 0]) }],
+    };
+
+    if (shouldPlaceAbove) {
+      style.top = Math.max(10, safeTargetY - safeTooltipHeight - 20);
+      style.bottom = undefined;
+    } else {
+      style.top = safeTargetY + safeTargetHeight + 20;
+      style.bottom = undefined;
+    }
+
+    return style;
+  });
+
+  if (!currentStepData) return null;
+
+  const AnimatedView = Animated.View as unknown as ComponentType<any>;
+
+  const handleTooltipLayout = (event: any) => {
+    const { height } = event.nativeEvent.layout;
+    if (height > 0) {
+      tooltipHeight.value = height;
+    }
+  };
+
+  // Custom Render
+  if (config?.renderCard) {
+    const cardProps: CardProps = {
+      step: currentStepData,
+      currentStepIndex: currentIndex,
+      totalSteps,
+      next,
+      prev,
+      stop,
+      isFirst,
+      isLast,
+      labels: config.labels,
+    };
+    return (
+      <AnimatedView
+        style={[
+          styles.container,
+          tooltipStyle,
+          // Reset styles for custom render so the user has full control
+          {
+            backgroundColor: 'transparent',
+            shadowOpacity: 0,
+            elevation: 0,
+            padding: 0,
+            borderRadius: 0,
+          },
+        ]}
+        onLayout={handleTooltipLayout}
+      >
+        {config.renderCard(cardProps)}
+      </AnimatedView>
+    );
+  }
+
+  // Default Render
+  const labels = { ...DEFAULT_LABELS, ...config?.labels };
+  const labelNext = isLast ? labels.finish : labels.next;
+  const labelSkip = labels.skip;
+
+  return (
+    <AnimatedView
+      // Combined styles: Container (Shadows) + CardStyle (White BG) + TooltipStyle (Position/Opacity)
+      style={[styles.container, styles.cardStyle, tooltipStyle]}
+      onLayout={handleTooltipLayout}
+    >
+      <View style={styles.header}>
+        <Text style={styles.title}>{currentStepData.name || 'Step'}</Text>
+        <Text style={styles.stepIndicator}>
+          {currentIndex + 1} / {totalSteps}
+        </Text>
+      </View>
+      <Text style={styles.description}>{currentStepData.description}</Text>
+
+      <View style={styles.footer}>
+        {!isLast && (
+          <TouchableOpacity onPress={stop} style={styles.buttonText}>
+            <Text style={styles.skipText}>{labelSkip}</Text>
+          </TouchableOpacity>
+        )}
+        {isLast && <View style={{ width: 10 }} />}
+
+        <TouchableOpacity onPress={next} style={styles.buttonPrimary}>
+          <Text style={styles.primaryButtonText}>{labelNext}</Text>
+        </TouchableOpacity>
+      </View>
+    </AnimatedView>
+  );
+});
+
+const styles = StyleSheet.create({
+  container: {
+    // Shadow Props
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 4 },
+    shadowOpacity: 0.3,
+    shadowRadius: 5,
+    elevation: 8,
+    zIndex: 999,
+  },
+  cardStyle: {
+    backgroundColor: 'white', // Ensure this is solid white
+    borderRadius: 12,
+    padding: 20,
+    minHeight: 120,
+  },
+  header: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    marginBottom: 8,
+  },
+  stepIndicator: {
+    fontSize: 12,
+    color: '#999',
+  },
+  title: {
+    fontSize: 18,
+    fontWeight: 'bold',
+    color: '#000',
+    flex: 1,
+  },
+  description: {
+    fontSize: 15,
+    color: '#444',
+    marginBottom: 20,
+    lineHeight: 22,
+  },
+  footer: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+  },
+  buttonText: {
+    padding: 8,
+  },
+  skipText: {
+    color: '#666',
+    fontWeight: '600',
+  },
+  buttonPrimary: {
+    backgroundColor: '#007AFF',
+    paddingVertical: 10,
+    paddingHorizontal: 20,
+    borderRadius: 25,
+  },
+  primaryButtonText: {
+    color: '#fff',
+    fontWeight: 'bold',
+    fontSize: 14,
+  },
+});