react-native-tuto-showcase 1.0.6 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # 🔦 **react-native-tuto-showcase**
 
-> Fully customizable **Spotlight / Tutorial / Coachmark overlay** for React Native — perfect for onboarding, feature discovery & guided tours.
+**Fully Customizable Spotlight / Tutorial / Coachmark Overlay for React Native — Perfect for Onboarding, Feature Discovery & Guided Tours**
 
 [![npm version](https://img.shields.io/npm/v/react-native-tuto-showcase.svg)](https://www.npmjs.com/package/react-native-tuto-showcase)
 [![license](https://img.shields.io/npm/l/react-native-tuto-showcase.svg)](https://github.com/ahmedhegazydev/react-native-tuto-showcase/blob/master/LICENSE)
@@ -15,7 +15,7 @@ A lightweight yet powerful **spotlight / walkthrough / coachmark** component for
 * Explain **complex UI**
 * Drive **feature adoption & discovery**
 
-Now with **full-screen Lottie placement** + **custom offsets**.
+Now with **full-screen Lottie placement**, **custom offsets**, and **smart tooltips**.
 
 ---
 
@@ -40,6 +40,13 @@ Now with **full-screen Lottie placement** + **custom offsets**.
     * `bottom-left`, `bottom-center`, `bottom-right`
     * `center`
   * Fine-tune with `lottieOffset={{ dx, dy }}`
+* 💬 **Tooltips (Coachmark Bubble) — NEW**
+
+  * Custom tooltip bubble near the spotlight target
+  * Smart placement: `auto | above | below`
+  * RTL-aware arrow positioning (`left | center`)
+  * Custom arrow inset & spacing
+  * Fully customizable background & layout
 * 📦 **Multiple spots on one screen**
 
   * Chain calls on the same ref (circle / rect / gestures)
@@ -52,8 +59,8 @@ Now with **full-screen Lottie placement** + **custom offsets**.
 
   * Overlay color
   * Button container & text style
-  * Custom title & description JSX
-  * Works great with your design system / theming
+  * Custom title / description JSX
+  * Optional tooltip bubble
 * 📱 **Cross-platform**
 
   * iOS & Android
@@ -72,7 +79,7 @@ npm install react-native-tuto-showcase
 yarn add react-native-tuto-showcase
 ```
 
-No extra native setup required beyond your standard React Native project.
+No extra native setup required.
 
 ---
 
@@ -92,10 +99,7 @@ export default function Home() {
       <TutoShowcase
         ref={tutoRef}
         title={<Text style={{ color: '#fff', fontSize: 22 }}>ترتيب الأقسام</Text>}
-        description={
-          'يمكنك سحب هذا القسم لأعلى أو لأسفل لتغيير ترتيبه.\n' +
-          'سيتم حفظ الترتيب تلقائيًا.'
-        }
+        description="يمكنك سحب هذا القسم لأعلى أو لأسفل لتغيير ترتيبه."
         buttonText="تمام"
       />
 
@@ -124,13 +128,13 @@ export default function Home() {
 
 ---
 
-## 🎞 Lottie Placement (New)
+## 🎞 Lottie Placement
 
-By default, the Lottie view is positioned **relative to the full screen**, so you can use it as a **hero pointer / hand animation** independent from the spotlight.
+The Lottie animation is positioned **relative to the full screen**, not the spotlight.
 
-### 🔹 Available placements
+### Available placements
 
-```text
+```
 top-left
 top-center
 top-right
@@ -140,7 +144,7 @@ bottom-right
 center
 ```
 
-### 🔹 Example
+### Example
 
 ```tsx
 import LottieView from 'lottie-react-native';
@@ -162,54 +166,88 @@ import LottieView from 'lottie-react-native';
 
 ---
 
+## 💬 Tooltip (New)
+
+Render a **custom tooltip bubble** near the highlighted target instead of the default title/description section.
+
+### Example
+
+```tsx
+<TutoShowcase
+  ref={tutoRef}
+  tooltip={
+    <Text style={{ color: '#fff', fontSize: 16, lineHeight: 22 }}>
+      Tap here to open your profile settings
+    </Text>
+  }
+  tooltipPlacement="auto"
+  tooltipArrowSide="left"
+  tooltipArrowInset={24}
+  tooltipGap={14}
+  tooltipBackgroundColor="#3B3563"
+/>
+```
+
+### Notes
+
+* When `tooltip` is provided, the default `title / description` section will **not render**.
+* Tooltip placement is calculated based on the **first spotlight target**.
+* Tooltip arrow automatically flips based on placement (`above / below`).
+* Fully RTL-aware.
+
+---
+
 ## 🧩 `<TutoShowcase />` Props
 
-| Prop                     | Type                           | Default            | Description                          |
-| ------------------------ | ------------------------------ | ------------------ | ------------------------------------ |
-| `title`                  | `ReactNode`                    | —                  | Title JSX (text, icons, etc.)        |
-| `description`            | `string \| ReactNode`          | —                  | Description text or custom JSX       |
-| `buttonText`             | `string`                       | `"GOT IT"`         | CTA button label                     |
-| `buttonTextStyle`        | `TextStyle`                    | —                  | Style for CTA text                   |
-| `buttonContainerStyle`   | `ViewStyle`                    | —                  | Style for CTA button wrapper         |
-| `overlayBackgroundColor` | `string`                       | `rgba(0,0,0,0.78)` | Dim background overlay color         |
-| `onGotIt`                | `() => void`                   | —                  | Callback when CTA is pressed         |
-| `lottie`                 | `ReactElement`                 | —                  | Lottie animation component           |
-| `lottiePlacement`        | `"top-left" \| ...`            | `"top-center"`     | Full-screen placement of the Lottie  |
-| `lottieOffset`           | `{ dx?: number; dy?: number }` | `{}`               | Extra offset applied after placement |
-
-> 💡 You can pass any **custom JSX** for `title` / `description` to plug into your design system (e.g. `Text`, `Heading`, `Icon + Text`, etc.)
+| Prop                     | Type                           | Default            | Description         |
+| ------------------------ | ------------------------------ | ------------------ | ------------------- |
+| `title`                  | `ReactNode`                    | —                  | Title JSX           |
+| `description`            | `string \| ReactNode`          | —                  | Description content |
+| `buttonText`             | `string`                       | `"GOT IT"`         | CTA label           |
+| `buttonTextStyle`        | `TextStyle`                    | —                  | CTA text style      |
+| `buttonContainerStyle`   | `ViewStyle`                    | —                  | CTA container style |
+| `overlayBackgroundColor` | `string`                       | `rgba(0,0,0,0.78)` | Overlay color       |
+| `onGotIt`                | `() => void`                   | —                  | CTA callback        |
+| `lottie`                 | `ReactElement`                 | —                  | Lottie animation    |
+| `lottiePlacement`        | `Placement`                    | `"top-center"`     | Lottie position     |
+| `lottieOffset`           | `{ dx?: number; dy?: number }` | `{}`               | Lottie offset       |
+| `tooltip`                | `ReactNode`                    | —                  | Tooltip content     |
+| `tooltipOffset`          | `{ dx?: number; dy?: number }` | `{}`               | Tooltip offset      |
+| `tooltipPlacement`       | `"auto" \| "above" \| "below"` | `"auto"`           | Tooltip placement   |
+| `tooltipArrowSide`       | `"left" \| "center"`           | `"left"`           | Arrow alignment     |
+| `tooltipArrowInset`      | `number`                       | `24`               | Arrow inset         |
+| `tooltipGap`             | `number`                       | `14`               | Gap from target     |
+| `tooltipArrowGap`        | `number`                       | `6`                | Extra arrow gap     |
+| `tooltipEdgePadding`     | `number`                       | `12`               | Screen edge padding |
+| `tooltipBackgroundColor` | `string`                       | `#3B3563`          | Tooltip background  |
 
 ---
 
 ## 🎛 Ref API
 
 ```ts
-import { TutoShowcaseHandle } from 'react-native-tuto-showcase';
-
 const tutoRef = useRef<TutoShowcaseHandle>(null);
 ```
 
-| Method                                 | Description                                    |
-| -------------------------------------- | ---------------------------------------------- |
-| `on(ref)`                              | Attach spotlight to a target element `ref`     |
-| `addCircle(ratio?)`                    | Add **circular** spotlight                     |
-| `addRoundRect(ratio?, radius?, opts?)` | Add **rounded-rectangle** spotlight            |
-| `withBorder()`                         | Add border around spotlight                    |
-| `displaySwipableLeft()`                | Show swipe-left gesture hint                   |
-| `displaySwipableRight()`               | Show swipe-right gesture hint                  |
-| `displayScrollable()`                  | Show scroll gesture hint                       |
-| `onClick(cb)`                          | Capture taps inside spotlight area             |
-| `show()`                               | Show tutorial immediately                      |
-| `showOnce(key)`                        | Show only once per key (saved in AsyncStorage) |
-| `resetShowOnce(key)`                   | Clear stored key; show again next time         |
-| `isShowOnce(key)`                      | Check if a specific key has already been shown |
+| Method                                 | Description                |
+| -------------------------------------- | -------------------------- |
+| `on(ref)`                              | Attach spotlight to target |
+| `addCircle(ratio?)`                    | Circular spotlight         |
+| `addRoundRect(ratio?, radius?, opts?)` | Rounded rectangle          |
+| `withBorder()`                         | Border around spotlight    |
+| `displaySwipableLeft()`                | Swipe-left hint            |
+| `displaySwipableRight()`               | Swipe-right hint           |
+| `displayScrollable()`                  | Scroll hint                |
+| `onClick(cb)`                          | Capture clicks             |
+| `show()`                               | Show immediately           |
+| `showOnce(key)`                        | Show once only             |
+| `resetShowOnce(key)`                   | Reset key                  |
+| `isShowOnce(key)`                      | Check key                  |
 
 ---
 
 ## 🗂 Show Once Logic
 
-Use `showOnce(key)` to avoid spamming users with the same tutorial:
-
 ```tsx
 tutoRef.current
   ?.on(boxRef)
@@ -217,111 +255,33 @@ tutoRef.current
   .showOnce('first-time-highlight');
 ```
 
-To reset:
+Reset:
 
 ```tsx
 tutoRef.current?.resetShowOnce('first-time-highlight');
 ```
 
-To check:
-
-```tsx
-const alreadyShown = await tutoRef.current?.isShowOnce('first-time-highlight');
-```
-
----
-
-## 🎨 Button & Overlay Customization
-
-```tsx
-<TutoShowcase
-  overlayBackgroundColor="rgba(15, 23, 42, 0.85)" // slate-like
-  buttonContainerStyle={{
-    backgroundColor: '#FFD700',
-    borderRadius: 999,
-    paddingHorizontal: 24,
-    paddingVertical: 10,
-  }}
-  buttonTextStyle={{
-    color: '#000',
-    fontWeight: 'bold',
-    fontSize: 16,
-  }}
-/>
-```
-
----
-
-## 📐 Spotlight Examples
-
-### Circle
-
-```tsx
-tutoRef.current
-  ?.on(boxRef)
-  .addCircle(1.3) // 1.0 = tight, >1 expands radius
-  .show();
-```
-
-### Rounded Rectangle
-
-```tsx
-tutoRef.current
-  ?.on(boxRef)
-  .addRoundRect(1.1, 20, { pad: 30 }) // ratio, corner radius, extra padding
-  .show();
-```
-
----
-
-## 🎥 Demo Videos
-
-### 📱 iOS
-
-[View iOS demo GIF](https://github.com/ahmedhegazydev/react-native-tuto-showcase/blob/master/src/assets/SimulatorScreenRecording-iPhone16Pro-2025-11-24at14.14.46online-video-cutter.com-ezgif.com-video-to-gif-converter.gif)
-
-### 🤖 Android
-
-[View Android demo GIF](https://github.com/ahmedhegazydev/react-native-tuto-showcase/blob/master/src/assets/ScreenRecording2025-12-02at7.52.23PMonline-video-cutter.com-ezgif.com-video-to-gif-converter.gif)
-
 ---
 
 ## 🧠 Typical Use Cases
 
-* App **onboarding** & first-time user experience
-* Feature discovery (“What’s new” walkthroughs)
-* Highlighting **FAB buttons**, menus, tabs, drawers
-* Teaching users **drag & drop** / **reorder** interactions
-* Coachmarks for:
-
-  * Dashboards
-  * Settings screens
-  * Maps & complex UI
-* Internal QA / UX testing sessions
-
----
-
-## 🛠 Troubleshooting
-
-| Issue                           | Hint                                                         |
-| ------------------------------- | ------------------------------------------------------------ |
-| Spotlight not aligned correctly | Ensure the target has a `ref` and is rendered on screen      |
-| Nothing shows up                | Check `tutoRef.current` is not `null` before calling methods |
-| `showOnce` not working          | Verify AsyncStorage is properly linked & no key collisions   |
-| Lottie is cut or off-screen     | Adjust `lottiePlacement` + `lottieOffset`                    |
+* App onboarding
+* Feature discovery
+* Coachmarks
+* Dashboards & settings
+* Drag & drop education
+* UX testing
 
 ---
 
 ## 🗺 Roadmap
 
-* ✅ Multiple-step walkthrough sequences
-* ✅ Better gesture presets
-* 🔜 RTL-aware layouts
-* 🔜 Built-in themes (light / dark)
-* 🔜 Auto “Next / Previous” between spots
-* 🔜 Expo Snack examples
-
-> PRs & feature requests are very welcome ✨
+* ✅ Tooltips
+* ✅ Lottie full-screen placement
+* 🔜 Multi-step sequences
+* 🔜 Built-in themes
+* 🔜 Next / Previous navigation
+* 🔜 Expo examples
 
 ---
 
@@ -330,17 +290,10 @@ tutoRef.current
 Built with ❤️ by **Ahmed Hegazy**
 
 * 📧 [ahmedmhegazy.eg@gmail.com](mailto:ahmedmhegazy.eg@gmail.com)
-* 🐙 GitHub: [@ahmedhegazydev](https://github.com/ahmedhegazydev)
+* 🐙 GitHub: @ahmedhegazydev
 
 ---
 
 ## 📄 License
 
-MIT © **Ahmed Mohamed Ali Ali Hegazy**
-
----
-
-## 🔍 SEO / Keywords
-
-**Keywords:**
-`react native tutorial` · `react native onboarding` · `react native coach marks` · `react native walkthrough` · `react native spotlight` · `react native highlight view` · `react native feature discovery` · `react native guided tour` · `react native tooltip overlay` · `react native help overlay` · `react native lottie overlay` · `react native interactive tutorial` · `react native drag reorder tutorial` · `react native product tour` · `react native showcase` · `react native hint` · `react native gesture hint` · `react native ux onboarding` · `react native step by step tutorial`
+MIT © **Ahmed Mohamed Ali Ali Hegazy**

package/dist/components/ContentSection.js

@@ -1,10 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { View, Text, Pressable, StyleSheet } from 'react-native';
 export default function ContentSection({ title, description, buttonText, buttonTextStyle, buttonContainerStyle, coords, onPress, }) {
-    return (_jsxs(View, { style: [
-            styles.contentBase,
-            coords,
-        ], children: [title ? _jsx(View, { style: styles.titleContainer, children: title }) : null, description ? (_jsx(View, { style: styles.description, children: description })) : null, _jsx(Pressable, { style: [styles.cta, buttonContainerStyle], onPress: onPress, children: _jsx(Text, { style: [styles.ctaText, buttonTextStyle], children: buttonText || 'GOT IT' }) })] }));
+    return (_jsxs(View, { style: [styles.contentBase, coords], children: [title ? _jsx(View, { style: styles.titleContainer, children: title }) : null, description ? _jsx(View, { style: styles.description, children: description }) : null, _jsx(Pressable, { style: [styles.cta, buttonContainerStyle], onPress: onPress, children: _jsx(Text, { style: [styles.ctaText, buttonTextStyle], children: buttonText || 'GOT IT' }) })] }));
 }
 const styles = StyleSheet.create({
     contentBase: {

package/dist/components/LottieAboveTarget.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import React from 'react';
-import { View, StyleSheet } from 'react-native';
+import { View, StyleSheet, } from 'react-native';
 const PADDING_H = 24;
 const PADDING_V = 32;
 export default function LottieAboveTarget({ shapes, lottie, overlayWidth, overlayHeight, placement = 'top-center', // 👈 الديفولت: فوق في النص بالنسبة للشاشة كلها

package/dist/helpers/buildActions.js

@@ -56,7 +56,7 @@ export function buildActionsFactory(setVisible, measureOverlayOrigin, setShapes,
                     const lr = toLocalRect(r, overlayOrigin);
                     setClickZones(p => [
                         ...p,
-                        { x: lr.x, y: lr.y, w: lr.width, h: lr.height, onClick }
+                        { x: lr.x, y: lr.y, w: lr.width, h: lr.height, onClick },
                     ]);
                 });
                 return expose;
@@ -107,10 +107,7 @@ export function buildActionsFactory(setVisible, measureOverlayOrigin, setShapes,
                         y += opts.dy;
                     const cx = x + w / 2;
                     const cy = y + h / 2;
-                    setShapes(p => [
-                        ...p,
-                        { type: 'roundrect', x, y, w, h, cx, cy, radius }
-                    ]);
+                    setShapes(p => [...p, { type: 'roundrect', x, y, w, h, cx, cy, radius }]);
                     setClickZones(p => [...p, { x, y, w, h, onClick: settings.onClick }]);
                 });
                 return editor(api);
@@ -122,7 +119,7 @@ export function buildActionsFactory(setVisible, measureOverlayOrigin, setShapes,
                     const lr = toLocalRect(r, overlayOrigin);
                     setHints(p => [
                         ...p,
-                        { kind: 'left', x: lr.x + lr.width * 0.7, y: lr.y + lr.height / 2 }
+                        { kind: 'left', x: lr.x + lr.width * 0.7, y: lr.y + lr.height / 2 },
                     ]);
                 });
                 return actionEditor(api);
@@ -132,10 +129,7 @@ export function buildActionsFactory(setVisible, measureOverlayOrigin, setShapes,
                     if (!r)
                         return;
                     const lr = toLocalRect(r, overlayOrigin);
-                    setHints(p => [
-                        ...p,
-                        { kind: 'right', x: lr.x, y: lr.y + lr.height / 2 }
-                    ]);
+                    setHints(p => [...p, { kind: 'right', x: lr.x, y: lr.y + lr.height / 2 }]);
                 });
                 return actionEditor(api);
             },
@@ -146,7 +140,7 @@ export function buildActionsFactory(setVisible, measureOverlayOrigin, setShapes,
                     const lr = toLocalRect(r, overlayOrigin);
                     setHints(p => [
                         ...p,
-                        { kind: 'scroll', x: lr.x + lr.width / 2, y: lr.y + lr.height * 0.1 }
+                        { kind: 'scroll', x: lr.x + lr.width / 2, y: lr.y + lr.height * 0.1 },
                     ]);
                 });
                 return actionEditor(api);
@@ -177,7 +171,7 @@ export function buildActionsFactory(setVisible, measureOverlayOrigin, setShapes,
             animated: a => {
                 settings.animated = a;
                 return actionEditor(api);
-            }
+            },
         };
         return api;
     };

package/dist/hooks/usePulseAnimation.js

@@ -15,29 +15,29 @@ export function usePulseAnimation(visible) {
                     toValue: SPOT_SCALE_MAX,
                     duration: SPOT_PULSE_MS,
                     easing: Easing.out(Easing.quad),
-                    useNativeDriver: true
+                    useNativeDriver: true,
                 }),
                 Animated.timing(opacity, {
                     toValue: 0.85,
                     duration: SPOT_PULSE_MS,
                     easing: Easing.out(Easing.quad),
-                    useNativeDriver: true
-                })
+                    useNativeDriver: true,
+                }),
             ]),
             Animated.parallel([
                 Animated.timing(scale, {
                     toValue: SPOT_SCALE_MIN,
                     duration: SPOT_PULSE_MS,
                     easing: Easing.in(Easing.quad),
-                    useNativeDriver: true
+                    useNativeDriver: true,
                 }),
                 Animated.timing(opacity, {
                     toValue: 1,
                     duration: SPOT_PULSE_MS,
                     easing: Easing.in(Easing.quad),
-                    useNativeDriver: true
-                })
-            ])
+                    useNativeDriver: true,
+                }),
+            ]),
         ]));
         loop.start();
         return () => loop.stop();

package/dist/index.d.ts

@@ -22,6 +22,25 @@ type TutoShowcaseProps = {
         dx?: number;
         dy?: number;
     };
+    tooltip?: React.ReactNode;
+    tooltipOffset?: {
+        dx?: number;
+        dy?: number;
+    };
+    tooltipArrowSide?: 'left' | 'center';
+    tooltipArrowInset?: number;
+    tooltipPlacement?: 'auto' | 'above' | 'below';
+    tooltipEdgePadding?: number;
+    tooltipGap?: number;
+    tooltipArrowGap?: number;
+    tooltipBackgroundColor?: string;
+    overlayPadding?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    allowOverflow?: boolean;
 };
 declare const TutoShowcase: React.ForwardRefExoticComponent<TutoShowcaseProps & React.RefAttributes<TutoShowcaseHandle>>;
 export default TutoShowcase;

package/dist/index.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { forwardRef, useState, useCallback, useImperativeHandle, useEffect, } from 'react';
-import { Modal, TouchableWithoutFeedback, View, StyleSheet, Dimensions, } from 'react-native';
+import { forwardRef, useState, useCallback, useImperativeHandle, useEffect, useMemo, } from 'react';
+import { Modal, TouchableWithoutFeedback, View, StyleSheet, Dimensions, I18nManager, } from 'react-native';
 import Overlay from './components/Overlay';
 import GestureHints from './components/GestureHints';
 import ContentSection from './components/ContentSection';
@@ -11,21 +11,25 @@ import { usePulseAnimation } from './hooks/usePulseAnimation';
 import { buildActionsFactory } from './helpers/buildActions';
 import { useContentPosition } from './hooks/useContentPosition';
 const DEFAULT_BG = 'rgba(0,0,0,0.78)';
+const ARROW_H = 12;
+function getBBox(shape) {
+    return { x: shape.x, y: shape.y, w: shape.w, h: shape.h };
+}
 const TutoShowcase = forwardRef(function Tuto({ title, description, buttonText = 'GOT IT', buttonTextStyle, buttonContainerStyle, overlayBackgroundColor, onGotIt, lottie, lottiePlacement, // 👈 خدناه من props
-lottieOffset, }, ref) {
+lottieOffset, tooltip, tooltipOffset, tooltipArrowSide = 'left', tooltipArrowInset = 24, tooltipPlacement = 'auto', tooltipEdgePadding = 12, tooltipGap = 14, tooltipArrowGap = 6, tooltipBackgroundColor = '#3B3563', overlayPadding, allowOverflow, }, ref) {
     // -------- Hooks يجب أن تكون في الأعلى وبنفس الترتيب دائماً --------
     const [visible, setVisible] = useState(false);
     const [bgColor, setBgColor] = useState(overlayBackgroundColor || DEFAULT_BG);
     const [shapes, setShapes] = useState([]);
     const [hints, setHints] = useState([]);
     const [clickZones, setClickZones] = useState([]);
-    const { rootRef, overlayOrigin, overlaySize, onLayout, measureOverlayOrigin, } = useOverlayMeasurements();
+    const { rootRef, overlayOrigin, overlaySize, onLayout, measureOverlayOrigin } = useOverlayMeasurements();
     const { scale: spotScale, opacity: spotOpacity } = usePulseAnimation(visible);
     const dims = Dimensions.get('window');
     const width = overlaySize.width || dims.width;
     const height = overlaySize.height || dims.height;
     const coords = useContentPosition(visible, shapes, height);
-    const { shownKeys, loaded, markShown, reset: resetShowOnce, isShown, } = useShowOnce();
+    const { shownKeys, loaded, markShown, reset: resetShowOnce, isShown } = useShowOnce();
     // لو اتغير الـ prop من برّه نحدث الـ state
     useEffect(() => {
         if (overlayBackgroundColor) {
@@ -82,12 +86,129 @@ lottieOffset, }, ref) {
             }
         }
     }, [clickZones]);
+    const [tooltipSize, setTooltipSize] = useState({ w: 0, h: 0 });
+    const targetBox = useMemo(() => {
+        if (!shapes?.length)
+            return null;
+        return getBBox(shapes[0]);
+    }, [shapes]);
+    const tooltipPos = useMemo(() => {
+        if (!targetBox)
+            return null;
+        const dx = tooltipOffset?.dx ?? 0;
+        const dy = tooltipOffset?.dy ?? 0;
+        const padding = tooltipEdgePadding;
+        // 1) left centered on target + clamp
+        let left = targetBox.x + targetBox.w / 2 - tooltipSize.w / 2 + dx;
+        left = Math.max(padding, Math.min(left, width - tooltipSize.w - padding));
+        // 2) compute above/below
+        const gap = tooltipGap;
+        // arrowGap only for BELOW (because arrow is on top when below)
+        const arrowGapAbove = 0;
+        const arrowGapBelow = tooltipArrowGap;
+        const topAbove = targetBox.y - tooltipSize.h - ARROW_H - gap - arrowGapAbove + dy;
+        const topBelow = targetBox.y + targetBox.h + ARROW_H + gap + arrowGapBelow + dy;
+        const fitsAbove = topAbove >= padding;
+        const fitsBelow = topBelow + tooltipSize.h <= height - padding;
+        // 3) choose placement
+        let placement = tooltipPlacement === 'above'
+            ? 'above'
+            : tooltipPlacement === 'below'
+                ? 'below'
+                : fitsAbove
+                    ? 'above'
+                    : 'below';
+        if (placement === 'below' && !fitsBelow && fitsAbove)
+            placement = 'above';
+        if (placement === 'above' && !fitsAbove && fitsBelow)
+            placement = 'below';
+        // 4) final top clamp
+        let top = placement === 'above' ? topAbove : topBelow;
+        top = Math.max(padding, Math.min(top, height - tooltipSize.h - padding));
+        // 5) Arrow position inside tooltip
+        const inset = tooltipArrowInset;
+        const isRTL = I18nManager.isRTL;
+        let arrowLeft;
+        if (tooltipArrowSide === 'center') {
+            arrowLeft = Math.max(20, Math.min(tooltipSize.w - 40, tooltipSize.w / 2 - 14));
+        }
+        else {
+            // start edge: LTR->left, RTL->right
+            arrowLeft = !isRTL ? Math.max(20, tooltipSize.w - inset - 28) : inset;
+        }
+        return { left, top, arrowLeft, placement };
+    }, [
+        targetBox,
+        tooltipSize,
+        width,
+        height,
+        tooltipOffset,
+        tooltipArrowSide,
+        tooltipArrowInset,
+        tooltipPlacement,
+        tooltipEdgePadding,
+        tooltipGap,
+        tooltipArrowGap,
+    ]);
+    const shouldRenderContentSection = !tooltip && (title || description);
+    const pad = overlayPadding || {};
+    const padRight = pad.right ?? 0;
+    const padLeft = pad.left ?? 0;
     // ✅ الشرط هنا بعد كل الـ hooks
     if (!visible)
         return null;
-    return (_jsx(Modal, { visible: true, transparent: true, animationType: "fade", children: _jsx(TouchableWithoutFeedback, { onPress: onOverlayPress, children: _jsxs(View, { ref: rootRef, onLayout: onLayout, style: [StyleSheet.absoluteFill, { direction: 'ltr' }], children: [_jsx(Overlay, { width: width, height: height, shapes: shapes, bgColor: bgColor, spotScale: spotScale, spotOpacity: spotOpacity }), lottie && (_jsx(LottieAboveTarget, { shapes: shapes, lottie: lottie, overlayWidth: width, overlayHeight: height, placement: lottiePlacement, offset: lottieOffset })), (title || description) && (_jsx(ContentSection, { title: title, description: description, buttonText: buttonText, buttonTextStyle: buttonTextStyle, buttonContainerStyle: buttonContainerStyle, coords: coords, onPress: () => {
-                            onGotIt?.();
-                            dismiss();
-                        } })), _jsx(GestureHints, { hints: hints })] }) }) }));
+    return (_jsx(Modal, { visible: true, transparent: true, animationType: "fade", children: _jsx(TouchableWithoutFeedback, { onPress: onOverlayPress, children: _jsxs(View, { ref: rootRef, onLayout: onLayout, style: [StyleSheet.absoluteFill, { direction: 'ltr' }], children: [_jsx(Overlay, { width: width, height: height, shapes: shapes, bgColor: bgColor, spotScale: spotScale, spotOpacity: spotOpacity }), _jsxs(View, { pointerEvents: "box-none", style: [
+                            StyleSheet.absoluteFill,
+                            {
+                                paddingLeft: padLeft,
+                                paddingRight: padRight,
+                                overflow: allowOverflow ? 'visible' : 'hidden',
+                            },
+                        ], children: [lottie && (_jsx(LottieAboveTarget, { shapes: shapes, lottie: lottie, overlayWidth: width, overlayHeight: height, placement: lottiePlacement, offset: lottieOffset })), !!tooltip && !!tooltipPos && (_jsxs(View, { onLayout: e => {
+                                    const w = e.nativeEvent.layout.width;
+                                    const h = e.nativeEvent.layout.height;
+                                    if (w !== tooltipSize.w || h !== tooltipSize.h)
+                                        setTooltipSize({ w, h });
+                                }, style: {
+                                    position: 'absolute',
+                                    left: tooltipPos.left,
+                                    top: tooltipPos.top,
+                                }, children: [_jsx(View, { style: {
+                                            backgroundColor: tooltipBackgroundColor,
+                                            borderRadius: 28,
+                                            paddingVertical: 22,
+                                            paddingHorizontal: 26,
+                                            minWidth: 280,
+                                            maxWidth: width - 24,
+                                        }, children: tooltip }), _jsx(View, { style: tooltipPos.placement === 'above'
+                                            ? {
+                                                position: 'absolute',
+                                                bottom: -ARROW_H + 2,
+                                                left: tooltipPos.arrowLeft,
+                                                width: 0,
+                                                height: 0,
+                                                borderLeftWidth: 14,
+                                                borderRightWidth: 14,
+                                                borderTopWidth: ARROW_H,
+                                                borderLeftColor: 'transparent',
+                                                borderRightColor: 'transparent',
+                                                borderTopColor: tooltipBackgroundColor,
+                                            }
+                                            : {
+                                                position: 'absolute',
+                                                top: -ARROW_H + 2,
+                                                left: tooltipPos.arrowLeft,
+                                                width: 0,
+                                                height: 0,
+                                                borderLeftWidth: 14,
+                                                borderRightWidth: 14,
+                                                borderBottomWidth: ARROW_H,
+                                                borderLeftColor: 'transparent',
+                                                borderRightColor: 'transparent',
+                                                borderBottomColor: tooltipBackgroundColor,
+                                            } })] })), shouldRenderContentSection && (_jsx(ContentSection, { title: title, description: description, buttonText: buttonText, buttonTextStyle: buttonTextStyle, buttonContainerStyle: buttonContainerStyle, coords: coords, onPress: () => {
+                                    onGotIt?.();
+                                    dismiss();
+                                } })), _jsx(GestureHints, { hints: hints })] })] }) }) }));
 });
 export default TutoShowcase;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-tuto-showcase",
-  "version": "1.0.6",
+  "version": "2.0.0",
   "description": "Customizable tutorial / spotlight overlay for React Native (onboarding, feature tours, coachmarks).",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,7 +13,9 @@
     "url": "https://github.com/ahmedhegazydev/react-native-tuto-showcase.git"
   },
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "format": "prettier --write \"src/**/*.{js,jsx,ts,tsx,json,md}\"",
+    "format:check": "prettier --check \"src/**/*.{js,jsx,ts,tsx,json,md}\""
   },
   "keywords": [
     "react-native",
@@ -22,7 +24,26 @@
     "spotlight",
     "showcase",
     "coachmark",
-    "overlay"
+    "overlay",
+    "react native tutorial",
+    "react native onboarding",
+    "react native coach marks",
+    "react native walkthrough",
+    "react native spotlight",
+    "react native highlight view",
+    "react native feature discovery",
+    "react native guided tour",
+    "react native tooltip overlay",
+    "react native help overlay",
+    "react native lottie overlay",
+    "react native interactive tutorial",
+    "react native drag reorder tutorial",
+    "react native product tour",
+    "react native showcase",
+    "react native hint",
+    "react native gesture hint",
+    "react native ux onboarding",
+    "react native step by step tutorial"
   ],
   "author": "Ahmed Mohamed Ali Ali Hegazy",
   "license": "MIT",
@@ -37,6 +58,7 @@
     "@react-native-async-storage/async-storage": "^1.23.0",
     "@types/react": "^19.2.7",
     "@types/react-native": "^0.72.8",
+    "prettier": "^3.7.4",
     "react-native-svg": "^13.14.0",
     "typescript": "^5.9.3"
   }