From 1fc4fc6e311891ac85905163eb0aec1918329567 Mon Sep 17 00:00:00 2001
From: Akmal Mstfa <akmalmstfa29@gmail.com>
Date: Wed, 25 Jun 2025 10:57:45 +0700
Subject: [PATCH] feat(tour-overlay): add maskOffset and edge-to-edge or
 translucent support for android

Add support for translucent status/navigation bars on Android and allow adjusting the spotlight position with maskOffset. These changes enable better integration with edge-to-edge UI designs.
---
 package/src/lib/SpotlightTour.provider.tsx    | 22 +++++++++++++++++++
 .../tour-overlay/TourOverlay.component.tsx    | 11 +++++++++-
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/package/src/lib/SpotlightTour.provider.tsx b/package/src/lib/SpotlightTour.provider.tsx
index 6ea53bc..9fe5741 100644
--- a/package/src/lib/SpotlightTour.provider.tsx
+++ b/package/src/lib/SpotlightTour.provider.tsx
@@ -36,6 +36,15 @@ export interface SpotlightTourProviderProps extends TooltipProps {
    * argument.
    */
   children: ChildFn<SpotlightTour> | React.ReactNode;
+  /**
+   * Additional y position around the spotlight target point to account for
+   * UI elements like status bars or navigation bars, especially when using
+   * translucent or edge-to-edge modes. This creates extra space between the
+   * target element and the spotlight mask.
+   *
+   * @default 0
+   */
+  maskOffset?: number;
   /**
    * Sets the default transition motion for all steps. You can override this
    * value on each step too.
@@ -107,6 +116,15 @@ export interface SpotlightTourProviderProps extends TooltipProps {
    * An array of `TourStep` objects that define each step of the tour.
    */
   steps: TourStep[];
+  /**
+   * Android only: Enable translucent status and navigation bars to allow the
+   * tour overlay to extend behind system bars. Uses react-native-edge-to-edge
+   * internally to handle the translucent bars setup.
+   *
+   * @platform android
+   * @default false
+   */
+  translucent?: boolean;
 }
 
 /**
@@ -117,6 +135,7 @@ export const SpotlightTourProvider = forwardRef<SpotlightTour, SpotlightTourProv
     arrow,
     children,
     flip,
+    maskOffset = 0,
     motion = "bounce",
     nativeDriver = true,
     offset,
@@ -130,6 +149,7 @@ export const SpotlightTourProvider = forwardRef<SpotlightTour, SpotlightTourProv
     shape = "circle",
     shift,
     steps,
+    translucent,
   } = props;
 
   const [current, setCurrent] = useState<number>();
@@ -271,6 +291,7 @@ export const SpotlightTourProvider = forwardRef<SpotlightTour, SpotlightTourProv
         backdropOpacity={overlayOpacity}
         color={overlayColor}
         current={current}
+        maskOffset={maskOffset}
         motion={motion}
         nativeDriver={nativeDriver}
         onBackdropPress={onBackdropPress}
@@ -283,6 +304,7 @@ export const SpotlightTourProvider = forwardRef<SpotlightTour, SpotlightTourProv
         offset={offset}
         placement={placement}
         shift={shift}
+        translucent={translucent}
       />
     </SpotlightTourContext.Provider>
   );
diff --git a/package/src/lib/components/tour-overlay/TourOverlay.component.tsx b/package/src/lib/components/tour-overlay/TourOverlay.component.tsx
index 127c1d6..af21cd2 100644
--- a/package/src/lib/components/tour-overlay/TourOverlay.component.tsx
+++ b/package/src/lib/components/tour-overlay/TourOverlay.component.tsx
@@ -57,12 +57,14 @@ interface TourOverlayProps extends ToOptional<TooltipProps> {
   backdropOpacity: number;
   color: ColorValue;
   current: Optional<number>;
+  maskOffset?: number;
   motion: Motion;
   nativeDriver: boolean | OSConfig<boolean>;
   onBackdropPress: Optional<BackdropPressBehavior>;
   shape: Shape | ShapeOptions;
   spot: LayoutRectangle;
   tourStep: TourStep;
+  translucent?: boolean;
 }
 
 export const TourOverlay = forwardRef<TourOverlayRef, TourOverlayProps>((props, ref) => {
@@ -70,12 +72,14 @@ export const TourOverlay = forwardRef<TourOverlayRef, TourOverlayProps>((props,
     backdropOpacity,
     color,
     current,
+    maskOffset = 0,
     motion,
     nativeDriver,
     onBackdropPress,
     shape,
-    spot,
+    spot: defaultSpot,
     tourStep,
+    translucent,
     ...tooltipProps
   } = props;
 
@@ -83,6 +87,11 @@ export const TourOverlay = forwardRef<TourOverlayRef, TourOverlayProps>((props,
 
   const arrowRef = useRef<View>(null);
 
+  const spot = useMemo((): LayoutRectangle => ({
+    ...defaultSpot,
+    ...(translucent && { y: defaultSpot.y + maskOffset }),
+  }), [defaultSpot, translucent, maskOffset]);
+
   const floating = useMemo((): TooltipProps => ({
     arrow: tourStep.arrow ?? tooltipProps.arrow,
     flip: tourStep.flip ?? tooltipProps.flip,