react-native-lumen 1.0.0 → 1.1.0

package/src/components/TourProvider.tsx

@@ -1,9 +1,9 @@
 import React, {
-  createContext,
   useState,
   useCallback,
   useMemo,
   useRef,
+  useEffect,
   type ComponentType,
 } from 'react';
 import {
@@ -12,29 +12,134 @@ import {
   withTiming,
   useAnimatedRef,
   default as Animated,
+  type WithSpringConfig,
 } from 'react-native-reanimated';
-import { StyleSheet } from 'react-native';
+import { StyleSheet, Dimensions } from 'react-native';
 import type {
   TourStep,
   MeasureResult,
   TourConfig,
   InternalTourContextType,
+  ZoneStyle,
+  StorageAdapter,
+  StepsOrder,
 } from '../types';
+import { TourContext } from '../context/TourContext';
 import { TourOverlay } from './TourOverlay';
 import { TourTooltip } from './TourTooltip';
 import {
   DEFAULT_BACKDROP_OPACITY,
   DEFAULT_SPRING_CONFIG,
+  DEFAULT_ZONE_STYLE,
+  resolveZoneStyle,
 } from '../constants/defaults';
+import {
+  detectStorage,
+  saveTourProgress,
+  loadTourProgress,
+  clearTourProgress,
+} from '../utils/storage';
+
+const { width: SCREEN_WIDTH, height: SCREEN_HEIGHT } = Dimensions.get('window');
+
+/**
+ * Computes the zone geometry based on element bounds and zone style.
+ * Handles different shapes: rounded-rect, circle, pill.
+ */
+function computeZoneGeometry(
+  element: MeasureResult,
+  style: Required<ZoneStyle>
+): {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  borderRadius: number;
+} {
+  const {
+    paddingTop,
+    paddingRight,
+    paddingBottom,
+    paddingLeft,
+    shape,
+    borderRadius,
+  } = style;
+
+  let sx: number, sy: number, sw: number, sh: number, sr: number;
+
+  switch (shape) {
+    case 'circle': {
+      // Create a circular zone that encompasses the element
+      const cx = element.x + element.width / 2;
+      const cy = element.y + element.height / 2;
+      // Use the larger dimension to create a circle, plus padding
+      const radius =
+        Math.max(element.width, element.height) / 2 + style.padding;
+      sx = cx - radius;
+      sy = cy - radius;
+      sw = radius * 2;
+      sh = radius * 2;
+      sr = radius;
+      break;
+    }
+    case 'pill': {
+      // Pill shape with fully rounded ends
+      sx = element.x - paddingLeft;
+      sy = element.y - paddingTop;
+      sw = element.width + paddingLeft + paddingRight;
+      sh = element.height + paddingTop + paddingBottom;
+      sr = sh / 2; // Fully rounded based on height
+      break;
+    }
+    case 'rounded-rect':
+    default: {
+      sx = element.x - paddingLeft;
+      sy = element.y - paddingTop;
+      sw = element.width + paddingLeft + paddingRight;
+      sh = element.height + paddingTop + paddingBottom;
+      sr = borderRadius;
+      break;
+    }
+  }
+
+  // Clamp to screen bounds
+  sx = Math.max(0, Math.min(sx, SCREEN_WIDTH - sw));
+  sy = Math.max(0, Math.min(sy, SCREEN_HEIGHT - sh));
+  sw = Math.min(sw, SCREEN_WIDTH - sx);
+  sh = Math.min(sh, SCREEN_HEIGHT - sy);
 
-export const TourContext = createContext<InternalTourContextType | null>(null);
+  // Ensure minimum size
+  const minSize = 40;
+  sw = Math.max(sw, minSize);
+  sh = Math.max(sh, minSize);
+
+  return { x: sx, y: sy, width: sw, height: sh, borderRadius: sr };
+}
 
 interface TourProviderProps {
   children: React.ReactNode;
   /**
-   * Optional custom steps order. If provided, the tour will follow this array of keys.
+   * Optional custom steps order. Supports two formats:
+   *
+   * **Flat array** (single-screen or simple multi-screen):
+   * ```
+   * stepsOrder={['bio', 'prompt', 'poll', 'filters', 'swipeableCards']}
+   * ```
+   *
+   * **Screen-grouped object** (multi-screen tours):
+   * ```
+   * stepsOrder={{
+   *   ProfileSelf: ['bio', 'prompt', 'poll'],
+   *   HomeSwipe: ['filters'],
+   *   SwipeableCards: ['swipeableCards'],
+   * }}
+   * ```
+   *
+   * When using the object format, steps are flattened in the order the screens appear.
+   * The tour automatically waits when advancing to a step on an unmounted screen,
+   * and resumes when that step's TourZone mounts.
    */
-  stepsOrder?: string[];
+  stepsOrder?: StepsOrder;
   /**
    * Initial overlay opacity. Default 0.5
    */
@@ -55,11 +160,57 @@ export const TourProvider: React.FC<TourProviderProps> = ({
 }) => {
   const [steps, setSteps] = useState<Record<string, TourStep>>({});
   const [currentStep, setCurrentStep] = useState<string | null>(null);
+  const [hasSavedProgress, setHasSavedProgress] = useState(false);
 
   // ref to access latest measurements without causing re-renders
   const measurements = useRef<Record<string, MeasureResult>>({});
   const containerRef = useAnimatedRef<any>();
 
+  // ─── Persistence Setup ─────────────────────────────────────────────────────
+  const persistenceConfig = config?.persistence;
+  const isPersistenceEnabled = persistenceConfig?.enabled ?? false;
+  const tourId = persistenceConfig?.tourId ?? 'default';
+  const autoResume = persistenceConfig?.autoResume ?? true;
+  const clearOnComplete = persistenceConfig?.clearOnComplete ?? true;
+  const maxAge = persistenceConfig?.maxAge;
+
+  // Get storage adapter (custom or auto-detected)
+  const storageAdapter = useMemo<StorageAdapter | null>(() => {
+    if (!isPersistenceEnabled) return null;
+    if (persistenceConfig?.storage) return persistenceConfig.storage;
+    const detected = detectStorage();
+    return detected.adapter;
+  }, [isPersistenceEnabled, persistenceConfig?.storage]);
+
+  // Check for saved progress on mount
+  useEffect(() => {
+    if (!isPersistenceEnabled || !storageAdapter) {
+      setHasSavedProgress(false);
+      return;
+    }
+
+    const checkSavedProgress = async () => {
+      try {
+        const savedProgress = await loadTourProgress(storageAdapter, tourId);
+        if (savedProgress) {
+          // Check if progress is expired
+          if (maxAge && Date.now() - savedProgress.timestamp > maxAge) {
+            await clearTourProgress(storageAdapter, tourId);
+            setHasSavedProgress(false);
+          } else {
+            setHasSavedProgress(true);
+          }
+        } else {
+          setHasSavedProgress(false);
+        }
+      } catch {
+        setHasSavedProgress(false);
+      }
+    };
+
+    checkSavedProgress();
+  }, [isPersistenceEnabled, storageAdapter, tourId, maxAge]);
+
   // --- Shared Values for Animations (Zero Bridge Crossing) ---
   // Initialize off-screen or 0
   const targetX = useSharedValue(0);
@@ -68,6 +219,41 @@ export const TourProvider: React.FC<TourProviderProps> = ({
   const targetHeight = useSharedValue(0);
   const targetRadius = useSharedValue(10); // Default border radius
   const opacity = useSharedValue(0); // 0 = hidden, 1 = visible
+  const zoneBorderWidth = useSharedValue(DEFAULT_ZONE_STYLE.borderWidth);
+
+  // Track current step's resolved zone style
+  const currentZoneStyle = useMemo<ZoneStyle | null>(() => {
+    if (!currentStep) return null;
+    const step = steps[currentStep];
+    if (!step) return null;
+    return resolveZoneStyle(config?.zoneStyle, step.zoneStyle);
+  }, [currentStep, steps, config?.zoneStyle]);
+
+  // Helper to get spring config for a step (supports per-step overrides)
+  const getSpringConfigForStep = useCallback(
+    (stepKey: string): WithSpringConfig => {
+      const step = steps[stepKey];
+      const stepStyle = step?.zoneStyle;
+      const baseConfig = config?.springConfig ?? DEFAULT_SPRING_CONFIG;
+
+      // Allow per-step spring overrides
+      if (
+        stepStyle?.springDamping !== undefined ||
+        stepStyle?.springStiffness !== undefined
+      ) {
+        return {
+          damping: stepStyle.springDamping ?? baseConfig.damping,
+          stiffness: stepStyle.springStiffness ?? baseConfig.stiffness,
+          mass: baseConfig.mass,
+          overshootClamping: baseConfig.overshootClamping,
+          restDisplacementThreshold: baseConfig.restDisplacementThreshold,
+          restSpeedThreshold: baseConfig.restSpeedThreshold,
+        };
+      }
+      return baseConfig;
+    },
+    [steps, config?.springConfig]
+  );
 
   // Helper to animate to a specific step's layout
   const animateToStep = useCallback(
@@ -93,19 +279,25 @@ export const TourProvider: React.FC<TourProviderProps> = ({
           return;
         }
 
-        const springConfig = config?.springConfig ?? DEFAULT_SPRING_CONFIG;
+        const step = steps[stepKey];
+        const resolvedStyle = resolveZoneStyle(
+          config?.zoneStyle,
+          step?.zoneStyle
+        );
+        const springConfig = getSpringConfigForStep(stepKey);
 
-        targetX.value = withSpring(measure.x, springConfig);
-        targetY.value = withSpring(measure.y, springConfig);
-        targetWidth.value = withSpring(measure.width, springConfig);
-        targetHeight.value = withSpring(measure.height, springConfig);
+        // Compute zone geometry based on style (handles shapes and padding)
+        const geo = computeZoneGeometry(measure, resolvedStyle);
 
-        // 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);
+        targetX.value = withSpring(geo.x, springConfig);
+        targetY.value = withSpring(geo.y, springConfig);
+        targetWidth.value = withSpring(geo.width, springConfig);
+        targetHeight.value = withSpring(geo.height, springConfig);
+        targetRadius.value = withSpring(geo.borderRadius, springConfig);
+        zoneBorderWidth.value = withSpring(
+          resolvedStyle.borderWidth,
+          springConfig
+        );
 
         // Ensure overlay is visible
         opacity.value = withTiming(backdropOpacity, { duration: 300 });
@@ -120,14 +312,22 @@ export const TourProvider: React.FC<TourProviderProps> = ({
       targetWidth,
       targetHeight,
       targetRadius,
+      zoneBorderWidth,
       opacity,
-      config?.springConfig,
+      getSpringConfigForStep,
       steps,
+      config?.zoneStyle,
     ]
   );
 
   const registerStep = useCallback((step: TourStep) => {
     setSteps((prev) => ({ ...prev, [step.key]: step }));
+    // If this step was pending (waiting for cross-screen mount), activate it
+    if (pendingStepRef.current === step.key) {
+      pendingStepRef.current = null;
+      setCurrentStep(step.key);
+      // Overlay opacity will be set by updateStepLayout when measurement arrives
+    }
   }, []);
 
   const unregisterStep = useCallback((key: string) => {
@@ -166,17 +366,25 @@ export const TourProvider: React.FC<TourProviderProps> = ({
       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;
+        const step = steps[key];
+        const resolvedStyle = resolveZoneStyle(
+          config?.zoneStyle,
+          step?.zoneStyle
+        );
+        const springConfig = getSpringConfigForStep(key);
 
-        targetX.value = withSpring(measure.x, springConfig);
-        targetY.value = withSpring(measure.y, springConfig);
-        targetWidth.value = withSpring(measure.width, springConfig);
-        targetHeight.value = withSpring(measure.height, springConfig);
+        // Compute zone geometry based on style
+        const geo = computeZoneGeometry(measure, resolvedStyle);
 
-        // Update radius if available
-        const step = steps[key];
-        const radius = step?.meta?.borderRadius ?? 10;
-        targetRadius.value = withSpring(radius, springConfig);
+        targetX.value = withSpring(geo.x, springConfig);
+        targetY.value = withSpring(geo.y, springConfig);
+        targetWidth.value = withSpring(geo.width, springConfig);
+        targetHeight.value = withSpring(geo.height, springConfig);
+        targetRadius.value = withSpring(geo.borderRadius, springConfig);
+        zoneBorderWidth.value = withSpring(
+          resolvedStyle.borderWidth,
+          springConfig
+        );
 
         // Ensure overlay is visible (fixes race condition where start() was called before measure)
         opacity.value = withTiming(backdropOpacity, { duration: 300 });
@@ -189,15 +397,25 @@ export const TourProvider: React.FC<TourProviderProps> = ({
       targetWidth,
       targetHeight,
       targetRadius,
+      zoneBorderWidth,
       opacity,
       backdropOpacity,
-      config?.springConfig,
+      getSpringConfigForStep,
+      config?.zoneStyle,
       steps,
     ]
   );
 
+  // Flatten stepsOrder (supports both string[] and Record<string, string[]>)
+  const flatStepsOrder = useMemo<string[] | undefined>(() => {
+    if (!initialStepsOrder) return undefined;
+    if (Array.isArray(initialStepsOrder)) return initialStepsOrder;
+    // Object format: flatten values in key order
+    return Object.values(initialStepsOrder).flat();
+  }, [initialStepsOrder]);
+
   const getOrderedSteps = useCallback(() => {
-    if (initialStepsOrder) return initialStepsOrder;
+    if (flatStepsOrder) return flatStepsOrder;
     // If order property exists on steps, sort by it.
     const stepKeys = Object.keys(steps);
     if (stepKeys.length > 0) {
@@ -212,65 +430,186 @@ export const TourProvider: React.FC<TourProviderProps> = ({
       }
     }
     return stepKeys;
-  }, [initialStepsOrder, steps]);
+  }, [flatStepsOrder, steps]);
+
+  // Pending step for cross-screen navigation
+  // When next/prev targets a step that isn't mounted yet, we store it here
+  // and resume when that step's TourZone registers.
+  const pendingStepRef = useRef<string | null>(null);
+
+  // Save progress when step changes
+  useEffect(() => {
+    if (!isPersistenceEnabled || !storageAdapter || !currentStep) return;
+
+    const ordered = getOrderedSteps();
+    const stepIndex = ordered.indexOf(currentStep);
+
+    if (stepIndex >= 0) {
+      saveTourProgress(storageAdapter, tourId, currentStep, stepIndex).catch(
+        () => {
+          // Silently ignore save errors
+        }
+      );
+    }
+  }, [
+    currentStep,
+    isPersistenceEnabled,
+    storageAdapter,
+    tourId,
+    getOrderedSteps,
+  ]);
 
   const start = useCallback(
-    (stepKey?: string) => {
+    async (stepKey?: string) => {
       const ordered = getOrderedSteps();
-      const firstStep = stepKey || ordered[0];
+
+      let targetStep = stepKey;
+
+      // If no specific step and autoResume is enabled, try to restore from storage
+      if (!targetStep && isPersistenceEnabled && storageAdapter && autoResume) {
+        try {
+          const savedProgress = await loadTourProgress(storageAdapter, tourId);
+          if (savedProgress) {
+            // Check if progress is expired
+            if (maxAge && Date.now() - savedProgress.timestamp > maxAge) {
+              await clearTourProgress(storageAdapter, tourId);
+              setHasSavedProgress(false);
+            } else if (ordered.includes(savedProgress.currentStepKey)) {
+              // Verify the saved step still exists in order
+              targetStep = savedProgress.currentStepKey;
+            }
+          }
+        } catch {
+          // Ignore load errors, start from beginning
+        }
+      }
+
+      const firstStep = targetStep || 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);
+        // Check if the target step is registered (mounted)
+        if (steps[firstStep]) {
+          setCurrentStep(firstStep);
+          setTimeout(() => animateToStep(firstStep), 0);
+        } else {
+          // Step not mounted yet (on a different screen) - set as pending
+          pendingStepRef.current = firstStep;
+          // Don't set currentStep or opacity - wait for TourZone to mount
+        }
       }
     },
-    [getOrderedSteps, animateToStep]
+    [
+      getOrderedSteps,
+      animateToStep,
+      steps,
+      isPersistenceEnabled,
+      storageAdapter,
+      autoResume,
+      tourId,
+      maxAge,
+    ]
   );
 
   const stop = useCallback(() => {
     setCurrentStep(null);
     opacity.value = withTiming(0, { duration: 300 });
+    // Note: We do NOT clear progress on stop - only on complete or explicit clearProgress
   }, [opacity]);
 
+  // Clear progress helper
+  const clearProgress = useCallback(async () => {
+    if (!isPersistenceEnabled || !storageAdapter) return;
+    try {
+      await clearTourProgress(storageAdapter, tourId);
+      setHasSavedProgress(false);
+    } catch {
+      // Silently ignore clear errors
+    }
+  }, [isPersistenceEnabled, storageAdapter, tourId]);
+
   const next = useCallback(() => {
     if (!currentStep) return;
+
+    // Block navigation if current step has completed === false
+    const currentStepData = steps[currentStep];
+    if (currentStepData?.completed === false) {
+      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 });
+      const nextStepKey = ordered[currentIndex + 1];
+      if (nextStepKey) {
+        // Check if the next step is registered (mounted)
+        if (steps[nextStepKey]) {
+          setCurrentStep(nextStepKey);
+          // 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 {
+          // Step not mounted yet (on a different screen) - set as pending
+          pendingStepRef.current = nextStepKey;
+          setCurrentStep(null);
+          opacity.value = withTiming(0, { duration: 300 });
+          // Persist pending step so it can be resumed
+          if (isPersistenceEnabled && storageAdapter) {
+            const stepIndex = ordered.indexOf(nextStepKey);
+            saveTourProgress(
+              storageAdapter,
+              tourId,
+              nextStepKey,
+              stepIndex
+            ).catch(() => {});
+          }
+        }
       } else {
         stop();
       }
     } else {
-      stop(); // End of tour
+      // End of tour - clear progress if configured
+      if (isPersistenceEnabled && clearOnComplete && storageAdapter) {
+        clearTourProgress(storageAdapter, tourId)
+          .then(() => setHasSavedProgress(false))
+          .catch(() => {});
+      }
+      stop();
     }
-  }, [currentStep, getOrderedSteps, stop, opacity, backdropOpacity]);
+  }, [
+    currentStep,
+    steps,
+    getOrderedSteps,
+    stop,
+    opacity,
+    backdropOpacity,
+    isPersistenceEnabled,
+    clearOnComplete,
+    storageAdapter,
+    tourId,
+  ]);
 
   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 });
+      const prevStepKey = ordered[currentIndex - 1];
+      if (prevStepKey) {
+        // Check if the previous step is registered (mounted)
+        if (steps[prevStepKey]) {
+          setCurrentStep(prevStepKey);
+          // Don't call animateToStep - let useFrameCallback handle position tracking
+          opacity.value = withTiming(backdropOpacity, { duration: 300 });
+        } else {
+          // Step not mounted (on a different screen) - set as pending
+          pendingStepRef.current = prevStepKey;
+          setCurrentStep(null);
+          opacity.value = withTiming(0, { duration: 300 });
+        }
       }
     }
-  }, [currentStep, getOrderedSteps, opacity, backdropOpacity]);
+  }, [currentStep, steps, getOrderedSteps, opacity, backdropOpacity]);
 
   const scrollViewRef = useAnimatedRef<any>();
 
@@ -294,6 +633,9 @@ export const TourProvider: React.FC<TourProviderProps> = ({
     // For now, let's just return the `scrollViewRef` we created.
   }, []);
 
+  // Expose ordered step keys for tooltip and external use
+  const orderedStepKeys = useMemo(() => getOrderedSteps(), [getOrderedSteps]);
+
   const value = useMemo<InternalTourContextType>(
     () => ({
       start,
@@ -310,11 +652,16 @@ export const TourProvider: React.FC<TourProviderProps> = ({
       targetHeight,
       targetRadius,
       opacity,
+      zoneBorderWidth,
       steps,
       config,
       containerRef,
       scrollViewRef,
       setScrollViewRef,
+      currentZoneStyle,
+      clearProgress,
+      hasSavedProgress,
+      orderedStepKeys,
     }),
     [
       start,
@@ -331,11 +678,16 @@ export const TourProvider: React.FC<TourProviderProps> = ({
       targetHeight,
       targetRadius,
       opacity,
+      zoneBorderWidth,
       steps,
       config,
-      // containerRef is stable
+      containerRef,
       scrollViewRef,
       setScrollViewRef,
+      currentZoneStyle,
+      clearProgress,
+      hasSavedProgress,
+      orderedStepKeys,
     ]
   );