react-native-lumen 1.0.0

package/src/components/TourZone.tsx

@@ -0,0 +1,372 @@
+import React, {
+  useEffect,
+  useCallback,
+  useRef,
+  type ComponentType,
+} from 'react';
+import type { ViewStyle, StyleProp } from 'react-native';
+import { useTour } from '../hooks/useTour';
+import {
+  useAnimatedRef,
+  measure,
+  useFrameCallback,
+  withSpring,
+  default as Animated,
+  type AnimatedRef,
+  useSharedValue,
+} from 'react-native-reanimated';
+import { Dimensions } from 'react-native';
+import type { InternalTourContextType } from '../types';
+
+const { height: SCREEN_HEIGHT } = Dimensions.get('window');
+
+const AnimatedView = Animated.View as unknown as ComponentType<any>;
+
+interface TourZoneProps {
+  stepKey: string;
+  name?: string;
+  description: string;
+  order?: number;
+  shape?: 'rect' | 'circle';
+  borderRadius?: number;
+  children: React.ReactNode;
+  style?: StyleProp<ViewStyle>;
+  clickable?: boolean;
+}
+
+export const TourZone: React.FC<TourZoneProps> = ({
+  stepKey,
+  name,
+  description,
+  order,
+  shape = 'rect',
+  borderRadius = 10,
+  children,
+  style,
+  clickable,
+}) => {
+  const {
+    registerStep,
+    unregisterStep,
+    updateStepLayout,
+    currentStep,
+    containerRef,
+    scrollViewRef,
+    targetX,
+    targetY,
+    targetWidth,
+    targetHeight,
+    targetRadius,
+    config,
+  } = useTour() as InternalTourContextType;
+  const viewRef = useAnimatedRef<any>();
+
+  const isActive = currentStep === stepKey;
+
+  // Track if we're currently scrolling to prevent position updates during scroll
+  const isScrolling = useSharedValue(false);
+  const hasScrolled = useRef(false);
+
+  // Signal when scroll completes (from JS thread)
+  const onScrollComplete = useCallback(() => {
+    isScrolling.value = false;
+  }, [isScrolling]);
+
+  /**
+   * UNIFIED MEASUREMENT FUNCTION (JS THREAD)
+   * Always measures relative to SCREEN (Viewport), not Content.
+   * This fixes the bug where measureLayout returned content-relative Y.
+   */
+  const measureJS = useCallback(() => {
+    if (isScrolling.value || !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,
+          _y: number,
+          width: number,
+          height: number,
+          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,
+              _cy: number,
+              _cw: number,
+              _ch: number,
+              containerPageX: number,
+              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;
+
+                updateStepLayout(stepKey, {
+                  x: finalX,
+                  y: finalY,
+                  width,
+                  height,
+                });
+              }
+            }
+          );
+        }
+      );
+    }
+  }, [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);
+
+  // Auto-scroll Effect
+  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 attemptCount = 0;
+    const maxAttempts = 3;
+
+    const attemptMeasurement = (delay: number) => {
+      const timeoutId = setTimeout(() => {
+        if (hasScrolled.current) return;
+
+        attemptCount++;
+
+        // 1. Check current visibility on screen
+        view.measure(
+          (
+            _mx: number,
+            _my: number,
+            mw: number,
+            mh: number,
+            px: number,
+            py: number
+          ) => {
+            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;
+
+              if (needsScroll) {
+                hasScrolled.current = true;
+                isScrolling.value = 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,
+                    _sy: number,
+                    _sw: number,
+                    _sh: number,
+                    scrollPx: number,
+                    scrollPy: number
+                  ) => {
+                    // 3. Measure Element relative to ScrollView Content
+                    if (view.measureLayout) {
+                      view.measureLayout(
+                        scroll,
+                        (contentX: number, contentY: number) => {
+                          // Calculate target scroll position (center the element)
+                          const centerY =
+                            contentY - viewportHeight / 2 + mh / 2 + 50;
+                          const scrollY = Math.max(0, centerY);
+
+                          // 4. Measure Container to map coordinates to Overlay space
+                          container.measure(
+                            (
+                              _cx: number,
+                              _cy: number,
+                              _cw: number,
+                              _ch: number,
+                              containerPx: number,
+                              containerPy: number
+                            ) => {
+                              // THE FIX: Add scrollPy (ScrollView's screen Y)
+                              // Visual Y = ScrollViewScreenY + (ElementContentY - ScrollAmount)
+                              const targetScreenY =
+                                scrollPy + contentY - scrollY - containerPy;
+
+                              // X is simpler: ScrollViewScreenX + ElementContentX - ContainerScreenX
+                              const targetScreenX =
+                                scrollPx + contentX - containerPx;
+
+                              updateStepLayout(stepKey, {
+                                x: targetScreenX,
+                                y: targetScreenY,
+                                width: mw,
+                                height: mh,
+                              });
+
+                              try {
+                                scroll.scrollTo({ y: scrollY, animated: true });
+                                // Wait for scroll animation
+                                setTimeout(() => onScrollComplete(), 800);
+                              } catch (e) {
+                                console.error(e);
+                                onScrollComplete();
+                              }
+                            }
+                          );
+                        }
+                      );
+                    }
+                  }
+                );
+              } 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,
+                    });
+                  }
+                );
+              }
+            } else if (attemptCount < maxAttempts) {
+              attemptMeasurement(150 * attemptCount);
+            }
+          }
+        );
+      }, delay);
+      return timeoutId;
+    };
+
+    const timeoutId = attemptMeasurement(150);
+    return () => clearTimeout(timeoutId);
+  }, [
+    isActive,
+    scrollViewRef,
+    viewRef,
+    stepKey,
+    isScrolling,
+    onScrollComplete,
+    containerRef,
+    updateStepLayout,
+  ]);
+
+  // Standard onLayout handler (uses the unified measureJS)
+  const onLayout = () => {
+    measureJS();
+  };
+
+  // Register step on mount
+  useEffect(() => {
+    registerStep({
+      key: stepKey,
+      name,
+      description,
+      order,
+      clickable,
+      meta: { shape, borderRadius },
+    });
+    return () => unregisterStep(stepKey);
+  }, [
+    stepKey,
+    name,
+    description,
+    order,
+    shape,
+    borderRadius,
+    registerStep,
+    registerStep,
+    unregisterStep,
+    clickable,
+  ]);
+
+  return (
+    <AnimatedView
+      ref={viewRef}
+      onLayout={onLayout}
+      style={style}
+      collapsable={false}
+    >
+      {children}
+    </AnimatedView>
+  );
+};

package/src/constants/animations.ts

@@ -0,0 +1,71 @@
+import type { WithSpringConfig } from 'react-native-reanimated';
+
+/**
+ * Default spring configuration matching Reanimated 3 defaults.
+ */
+export const Reanimated3DefaultSpringConfig: WithSpringConfig = {
+  damping: 10,
+  mass: 1,
+  stiffness: 100,
+};
+
+/**
+ * Spring configuration with duration.
+ */
+export const Reanimated3DefaultSpringConfigWithDuration: WithSpringConfig = {
+  duration: 1333,
+  dampingRatio: 0.5,
+};
+
+/**
+ * A bouncy and energetic spring configuration.
+ */
+export const WigglySpringConfig: WithSpringConfig = {
+  damping: 90,
+  mass: 4,
+  stiffness: 900,
+};
+
+/**
+ * A bouncy spring configuration with fixed duration.
+ */
+export const WigglySpringConfigWithDuration: WithSpringConfig = {
+  duration: 550,
+  dampingRatio: 0.75,
+};
+
+/**
+ * A gentle and smooth spring configuration.
+ */
+export const GentleSpringConfig: WithSpringConfig = {
+  damping: 120,
+  mass: 4,
+  stiffness: 900,
+};
+
+/**
+ * A gentle spring configuration with fixed duration.
+ */
+export const GentleSpringConfigWithDuration: WithSpringConfig = {
+  duration: 550,
+  dampingRatio: 1,
+};
+
+/**
+ * A snappy and responsive spring configuration.
+ */
+export const SnappySpringConfig: WithSpringConfig = {
+  damping: 110,
+  mass: 4,
+  stiffness: 900,
+  overshootClamping: true,
+};
+
+/**
+ * A snappy spring configuration with fixed duration.
+ */
+export const SnappySpringConfigWithDuration: WithSpringConfig = {
+  duration: 550,
+  dampingRatio: 0.92,
+  overshootClamping: true,
+};

package/src/constants/defaults.ts

@@ -0,0 +1,15 @@
+import type { WithSpringConfig } from 'react-native-reanimated';
+
+export const DEFAULT_SPRING_CONFIG: WithSpringConfig = {
+  damping: 20,
+  stiffness: 90,
+};
+
+export const DEFAULT_BACKDROP_OPACITY = 0.5;
+
+export const DEFAULT_LABELS = {
+  next: 'Next',
+  previous: 'Previous',
+  finish: 'Finish',
+  skip: 'Skip',
+};

package/src/hooks/useTour.ts

@@ -0,0 +1,10 @@
+import { useContext } from 'react';
+import { TourContext } from '../components/TourProvider';
+
+export const useTour = () => {
+  const context = useContext(TourContext);
+  if (!context) {
+    throw new Error('useTour must be used within a TourProvider');
+  }
+  return context;
+};

package/src/index.tsx

@@ -0,0 +1,8 @@
+export * from './types';
+export * from './components/TourProvider';
+export * from './components/TourZone';
+export * from './hooks/useTour';
+export { TourOverlay } from './components/TourOverlay';
+export { TourTooltip } from './components/TourTooltip';
+export * from './constants/defaults';
+export * from './constants/animations';

package/src/types/index.ts

@@ -0,0 +1,142 @@
+import type { WithSpringConfig, SharedValue } from 'react-native-reanimated';
+import React from 'react';
+
+export interface TourStep {
+  /**
+   * Unique key for this step.
+   */
+  key: string;
+  /**
+   * Optional display name/label for this step.
+   */
+  name?: string;
+  /**
+   * Description text to show in the tooltip.
+   */
+  description: string;
+  /**
+   * Optional order index. If not provided, registration order is used (or explicit ordering in context).
+   */
+  order?: number;
+  /**
+   * Optional data for custom tooltip rendering
+   */
+  meta?: any;
+  /**
+   * If true, allows user interaction with the target element.
+   * If false, interactions are blocked (default behavior depends on global config).
+   */
+  clickable?: boolean;
+}
+
+export interface MeasureResult {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export type StepMap = Record<string, TourStep>;
+
+export interface TourLabels {
+  next?: string;
+  previous?: string;
+  finish?: string;
+  skip?: string;
+}
+
+export interface CardProps {
+  step: TourStep;
+  currentStepIndex: number;
+  totalSteps: number;
+  next: () => void;
+  prev: () => void;
+  stop: () => void;
+  isFirst: boolean;
+  isLast: boolean;
+  labels?: TourLabels;
+}
+
+export interface TourConfig {
+  /**
+   * Animation configuration for the spotlight movement.
+   */
+  springConfig?: WithSpringConfig;
+  /**
+   * If true, prevents interaction with the underlying app while tour is active.
+   * Default: false (interactions allowed outside the tooltip, but overlay might block them depending on implementation).
+   */
+  preventInteraction?: boolean;
+  /**
+   * Custom labels for buttons.
+   */
+  labels?: TourLabels;
+  /**
+   * Custom renderer for the card/tooltip.
+   */
+  renderCard?: (props: CardProps) => React.ReactNode;
+  /**
+   * Backdrop opacity. Default 0.5
+   */
+  backdropOpacity?: number;
+}
+
+export interface TourContextType {
+  /**
+   * Starts the tour at the first step or a specific step (by key).
+   */
+  start: (stepKey?: string) => void;
+  /**
+   * Stops the tour and hides the overlay.
+   */
+  stop: () => void;
+  /**
+   * Advances to the next step.
+   */
+  next: () => void;
+  /**
+   * Goes back to the previous step.
+   */
+  prev: () => void;
+  /**
+   * Registers a zone/step.
+   */
+  registerStep: (step: TourStep) => void;
+  /**
+   * Unregisters a zone/step.
+   */
+  unregisterStep: (key: string) => void;
+  /**
+   * Updates the layout of a specific step.
+   * This is called by TourZone on layout/mount.
+   */
+  updateStepLayout: (key: string, measure: MeasureResult) => void;
+  /**
+   * The current active step key, or null if tour is inactive.
+   */
+  currentStep: string | null;
+  /**
+   * Map of registered steps.
+   */
+  steps: StepMap;
+  /**
+   * Global tour configuration
+   */
+  config?: TourConfig;
+  /**
+   * Registers the main ScrollView ref for auto-scrolling
+   */
+  setScrollViewRef: (ref: any) => void;
+}
+
+export interface InternalTourContextType extends TourContextType {
+  targetX: SharedValue<number>;
+  targetY: SharedValue<number>;
+  targetWidth: SharedValue<number>;
+  targetHeight: SharedValue<number>;
+  targetRadius: SharedValue<number>;
+  opacity: SharedValue<number>;
+  containerRef: React.RefObject<any>;
+  scrollViewRef: React.RefObject<any>;
+  setScrollViewRef: (ref: any) => void;
+}