fix: set translucentStatusBar prop

Author: GabrielaAndocilla

README.md

@@ -34,7 +34,27 @@ for the following:
 
 ## ✨ Edge-to-Edge Support
 
-This library supports edge-to-edge display, including Android 15's enforced edge-to-edge mode. The tour overlay automatically covers the full screen including system bars. When using edge-to-edge layouts, you may need to adjust spotlight positioning using the `coordinateAdjustment` prop or individual `offset` props on `AttachStep` components. See the [example app](example/) for a working edge-to-edge implementation.
+This library supports edge-to-edge display (including Android 15’s enforced mode). The tour overlay already covers the whole screen, system bars included.
+
+When your screens use a translucent status bar you can enable proper handling—and optionally nudge the spotlight—via the new `translucentStatusBar` prop:
+
+```tsx
+<SpotlightTourProvider
+  translucentStatusBar={{
+    enable: true,                 // overlay under system bars
+    coordinateAdjustment: { y: insets.top }, // y = status-bar height (e.g. use SafeArea insets.top)
+  }}
+  {...otherProps}
+>
+  {/* … */}
+</SpotlightTourProvider>
+```
+
+`insets.top` is the height of the status bar returned by `react-native-safe-area-context`. Any value that represents the actual status-bar height will work.
+
+`translucentStatusBar` is **optional**—if you omit it or set `enable` to `false`, the tour continues to behave exactly as before.
+
+See the [example app](example/) for a fully-working edge-to-edge implementation.
 
 ## Install
 

example/src/App.tsx

@@ -1,7 +1,7 @@
 import dedent from "dedent";
 import { type ReactElement, useCallback, useMemo } from "react";
-import { Alert, Animated, Button, Dimensions, Platform, StatusBar, Text, View, useAnimatedValue } from "react-native";
-import { SafeAreaProvider, useSafeAreaInsets } from "react-native-safe-area-context";
+import { Alert, Animated, Button, Dimensions, Text, useAnimatedValue } from "react-native";
+import { SafeAreaProvider, SafeAreaView, useSafeAreaInsets } from "react-native-safe-area-context";
 import {
   AttachStep,
   type RenderProps,
@@ -24,8 +24,7 @@ import { DocsTooltip } from "./DocsTooltip";
 
 function AppContent(): ReactElement {
   const gap = useAnimatedValue(0, { useNativeDriver: true });
-  const insets = useSafeAreaInsets();
-
+  const { top } = useSafeAreaInsets();
   const showSummary = useCallback(({ index, isLast }: TourState) => {
     Alert.alert(
       "Tour Finished",
@@ -121,24 +120,22 @@ function AppContent(): ReactElement {
   }], []);
 
   return (
-    <View style={{
-      flex: 1,
-      paddingTop: insets.top,
-    }}
-    >
-      <StatusBar translucent={true} backgroundColor="transparent" barStyle="dark-content" />
+    <SafeAreaView style={{ flex: 1 }}>
       <SpotlightTourProvider
         steps={tourSteps}
         overlayColor="gray"
-        overlayOpacity={0.36}
+        overlayOpacity={0.86}
         nativeDriver={true}
         onBackdropPress="continue"
         onStop={showSummary}
         onPause={alertPause}
         motion="bounce"
         shape="circle"
         arrow={{ color: "#B0C4DE" }}
-        coordinateAdjustment={Platform.OS === "android" ? { y: insets.top } : undefined}
+        translucentStatusBar={{
+          coordinateAdjustment: { y: top },
+          enable: true,
+        }}
       >
         {({ resume, start, status }: SpotlightTour) => (
           <>
@@ -188,7 +185,7 @@ function AppContent(): ReactElement {
           </>
         )}
       </SpotlightTourProvider>
-    </View>
+    </SafeAreaView>
   );
 }
 

package/src/lib/SpotlightTour.context.ts

@@ -153,11 +153,6 @@ export interface TooltipProps {
    * @default 20
    */
   arrow?: ArrowOptions | boolean | number;
-  /**
-   * Global coordinate adjustment for all spotlight calculations.
-   * Useful for edge-to-edge layouts or custom status bar configurations.
-   */
-  coordinateAdjustment?: CoordinateAdjustment;
   /**
    * Enables flipping the placement of the tooltip in order to keep it in view.
    *
@@ -182,6 +177,11 @@ export interface TooltipProps {
    * @default { padding: 8 }
    */
   shift?: boolean | ShiftOptions;
+  /**
+   * Global coordinate adjustment for all spotlight calculations.
+   * Useful for edge-to-edge layouts or custom status bar configurations.
+   */
+  translucentStatusBar?: TranslucentStatusBar;
 }
 
 export interface TourStep extends TooltipProps {
@@ -276,10 +276,6 @@ export interface SpotlightTourCtx extends SpotlightTour {
    * @param spot the spot layout
    */
   changeSpot: (spot: LayoutRectangle) => void;
-  /**
-   * Global coordinate adjustment for all spotlight calculations.
-   */
-  coordinateAdjustment?: CoordinateAdjustment;
   /**
    * The spotlight layout.
    */
@@ -288,6 +284,10 @@ export interface SpotlightTourCtx extends SpotlightTour {
    * The list of steps for the tour.
    */
   steps: TourStep[];
+  /**
+   * Global coordinate adjustment for all spotlight calculations.
+   */
+  translucentStatusBar?: TranslucentStatusBar;
 }
 
 export const ZERO_SPOT: LayoutRectangle = {
@@ -299,7 +299,6 @@ export const ZERO_SPOT: LayoutRectangle = {
 
 export const SpotlightTourContext = createContext<SpotlightTourCtx>({
   changeSpot: () => undefined,
-  coordinateAdjustment: undefined,
   goTo: () => undefined,
   next: () => undefined,
   pause: () => undefined,
@@ -310,6 +309,7 @@ export const SpotlightTourContext = createContext<SpotlightTourCtx>({
   status: "idle",
   steps: [],
   stop: () => undefined,
+  translucentStatusBar: undefined,
 });
 
 /**
@@ -332,7 +332,6 @@ export function useSpotlightTour(): SpotlightTour {
     stop,
   };
 }
-
 export interface CoordinateAdjustment {
   /**
    * Global X offset to apply to all spotlight calculations
@@ -343,3 +342,14 @@ export interface CoordinateAdjustment {
    */
   y?: number;
 }
+export interface TranslucentStatusBar {
+  /**
+   * Global coordinate adjustment for all spotlight calculations.
+   */
+  coordinateAdjustment?: CoordinateAdjustment;
+  /**
+   * Whether to enable the translucent status bar
+   */
+  enable?: boolean;
+
+}

package/src/lib/SpotlightTour.provider.tsx

@@ -116,7 +116,6 @@ export const SpotlightTourProvider = forwardRef<SpotlightTour, SpotlightTourProv
   const {
     arrow,
     children,
-    coordinateAdjustment,
     flip,
     motion = "bounce",
     nativeDriver = true,
@@ -131,6 +130,7 @@ export const SpotlightTourProvider = forwardRef<SpotlightTour, SpotlightTourProv
     shape = "circle",
     shift,
     steps,
+    translucentStatusBar,
   } = props;
 
   const [current, setCurrent] = useState<number>();
@@ -236,7 +236,6 @@ export const SpotlightTourProvider = forwardRef<SpotlightTour, SpotlightTourProv
 
   const tour = useMemo((): SpotlightTourCtx => ({
     changeSpot,
-    coordinateAdjustment,
     current,
     goTo,
     next,
@@ -248,7 +247,8 @@ export const SpotlightTourProvider = forwardRef<SpotlightTour, SpotlightTourProv
     status,
     steps,
     stop,
-  }), [changeSpot, coordinateAdjustment, current, goTo, next, previous, spot, start, steps, stop, pause]);
+    translucentStatusBar,
+  }), [changeSpot, translucentStatusBar, current, goTo, next, previous, spot, start, steps, stop, pause]);
 
   useImperativeHandle(ref, () => ({
     current,
@@ -270,7 +270,7 @@ export const SpotlightTourProvider = forwardRef<SpotlightTour, SpotlightTourProv
       }
 
       <TourOverlay
-        coordinateAdjustment={coordinateAdjustment}
+        translucentStatusBar={translucentStatusBar}
         backdropOpacity={overlayOpacity}
         color={overlayColor}
         current={current}

package/src/lib/components/attach-step/AttachStep.component.tsx

@@ -54,14 +54,6 @@ export interface AttachStepProps {
    * It can be a single index or multiple ones.
    */
   index: Array<number> | number;
-  /**
-   * Local offset adjustment for this specific AttachStep.
-   * This will be added to any global coordinate adjustment.
-   */
-  offset?: {
-    x?: number;
-    y?: number;
-  };
   /**
    * Style applied to AttachStep wrapper
    */
@@ -75,8 +67,9 @@ export interface AttachStepProps {
  * @param props the component props
  * @returns an AttachStep React element
  */
-export function AttachStep({ children, fill = false, index, offset, style }: AttachStepProps): ReactElement {
-  const { changeSpot, coordinateAdjustment, current } = useContext(SpotlightTourContext);
+export function AttachStep({ children, fill = false, index, style }: AttachStepProps):
+ReactElement {
+  const { changeSpot, current, translucentStatusBar } = useContext(SpotlightTourContext);
 
   const ref = useRef<View>(null);
 
@@ -85,22 +78,18 @@ export function AttachStep({ children, fill = false, index, offset, style }: Att
 
     if (current !== undefined && indexes.includes(current)) {
       ref.current?.measureInWindow((x, y, width, height) => {
-        // Apply global coordinate adjustment
+        if (!translucentStatusBar?.enable) {
+          changeSpot({ height, width, x, y });
+          return;
+        }
+        const { coordinateAdjustment } = translucentStatusBar;
         const globalX = coordinateAdjustment?.x || 0;
         const globalY = coordinateAdjustment?.y || 0;
 
-        // Apply local offset
-        const localX = offset?.x || 0;
-        const localY = offset?.y || 0;
-
-        // Combine all adjustments
-        const adjustedX = x + globalX + localX;
-        const adjustedY = y + globalY + localY;
-
-        changeSpot({ height, width, x: adjustedX, y: adjustedY });
+        changeSpot({ height, width, x: x + globalX, y: y + globalY });
       });
     }
-  }, [changeSpot, current, JSON.stringify(index), coordinateAdjustment, offset]);
+  }, [changeSpot, current, JSON.stringify(index), translucentStatusBar]);
 
   const onLayout = useCallback((event: LayoutChangeEvent): void => {
     updateSpot();

package/src/lib/components/tour-overlay/TourOverlay.component.tsx

@@ -79,7 +79,9 @@ export const TourOverlay = forwardRef<TourOverlayRef, TourOverlayProps>((props,
     ...tooltipProps
   } = props;
 
-  const { goTo, next, pause, previous, resume, start, steps, stop } = useContext(SpotlightTourContext);
+  const {
+    goTo, next, pause, previous, resume, start, steps, stop, translucentStatusBar,
+  } = useContext(SpotlightTourContext);
 
   const arrowRef = useRef<View>(null);
 
@@ -187,7 +189,7 @@ export const TourOverlay = forwardRef<TourOverlayRef, TourOverlayProps>((props,
       supportedOrientations={["portrait", "landscape", "landscape-left", "landscape-right", "portrait-upside-down"]}
       transparent={true}
       visible={current !== undefined}
-      statusBarTranslucent={true}
+      statusBarTranslucent={translucentStatusBar?.enable ?? false}
     >
       <View testID="Overlay View" style={Css.overlayView}>
         <Svg