react-native-tuto-showcase 1.0.3 → 1.0.5

package/README.md

@@ -4,51 +4,30 @@
 
 Perfect for onboarding flows, feature tours, highlighting UI elements, and guiding users interactively.
 
----
-
-# 📽 Demo
-
-### **iOS Showcase**
-
-<img 
-src="https://raw.githubusercontent.com/ahmedhegazydev/react-native-tuto-showcase/master/src/assets/SimulatorScreenRecording-iPhone16Pro-2025-11-24at14.14.46online-video-cutter.com-ezgif.com-video-to-gif-converter.gif"
-width="350"
-/>
-
----
-
-### **Android Showcase**
-
-<img 
-src="https://raw.githubusercontent.com/ahmedhegazydev/react-native-tuto-showcase/master/src/assets/ScreenRecording2025-12-02at7.52.23PMonline-video-cutter.com-ezgif.com-video-to-gif-converter.gif"
-width="350"
-/>
+Now with **full-screen Lottie placement** + **custom offsets**.
 
 ---
 
 # ✨ Features
 
-* 🎯 Highlight any UI element using **circle or rounded-rectangle spotlight**
-
+* 🎯 Highlight any UI element with **Circle / RoundRect** spotlight
 * 📐 Auto-calculated spotlight position using `measureInWindow`
-
-* 🔁 Show once / persistent keys using AsyncStorage
-
-* 🎞 Lottie animation support above target
-
-* 🕳 Multiple shapes per screen (multi-step tutorial)
-
-* ✋ Gesture hints (swipe left/right, scroll)
-
-* 🎨 Customizable:
-
-  * Overlay background color
-  * Button text, color, style
-  * Title & description
-  * Lottie size & position
-
-* 📱 Works on both **iOS & Android**
-
+* 🔁 Show-once logic (AsyncStorage)
+* 🎞 **Lottie Animations with full-screen positioning**
+
+  * `top-left`, `top-right`, `top-center`
+  * `bottom-left`, `bottom-right`, `bottom-center`
+  * `center`
+  * * `lottieOffset={{dx, dy}}`
+* 📦 Multiple spots on one screen
+* ✋ Gesture hints (swipe / scroll)
+* 🎨 Fully customizable:
+
+  * Colors
+  * Button style
+  * Fonts
+  * Overlay background
+* 📱 Works on **iOS & Android**
 * ⚡ Supports React Native 0.72+
 
 ---
@@ -61,20 +40,16 @@ npm install react-native-tuto-showcase
 yarn add react-native-tuto-showcase
 ```
 
-> Make sure you have `react-native-svg` installed (auto-installed as dependency).
-
 ---
 
-# 🚀 Usage Example
-
-### **Highlight a component inside your screen**
+# 🚀 Basic Usage
 
 ```tsx
 import React, { useRef } from 'react';
 import { View, Text, Pressable } from 'react-native';
 import TutoShowcase, { TutoShowcaseHandle } from 'react-native-tuto-showcase';
 
-export default function HomeScreen() {
+export default function Home() {
   const tutoRef = useRef<TutoShowcaseHandle>(null);
   const boxRef = useRef<View>(null);
 
@@ -84,27 +59,25 @@ export default function HomeScreen() {
         ref={tutoRef}
         title={<Text style={{ color: '#fff', fontSize: 22 }}>ترتيب الأقسام</Text>}
         description={
-          'يمكنك سحب هذا القسم لأعلى أو لأسفل لتغيير ترتيبه في الصفحة.\n' +
-          'سيتم حفظ الترتيب الجديد تلقائيًا.'
+          'يمكنك سحب هذا القسم لأعلى أو لأسفل لتغيير ترتيبه.\n' +
+          'سيتم حفظ الترتيب تلقائيًا.'
         }
         buttonText="تمام"
-        overlayBackgroundColor="rgba(0,0,0,0.85)"
-        buttonContainerStyle={{ backgroundColor: '#ff9800' }}
-        buttonTextStyle={{ color: '#000', fontWeight: 'bold' }}
       />
 
-      <View ref={boxRef} style={{ marginTop: 100, backgroundColor: '#eee', padding: 20 }}>
+      <View ref={boxRef} style={{ marginTop: 120, padding: 20, backgroundColor: '#eee' }}>
         <Text>Drag Me</Text>
       </View>
 
       <Pressable
-        onPress={() => {
+        onPress={() =>
           tutoRef.current
             ?.on(boxRef)
             .addRoundRect()
             .withBorder()
-            .showOnce('highlight-box');
-        }}>
+            .showOnce('highlight-box')
+        }
+      >
         <Text>Start Tutorial</Text>
       </Pressable>
     </>
@@ -114,58 +87,25 @@ export default function HomeScreen() {
 
 ---
 
-# 🧩 API Documentation
+# 🎞 Lottie Placement (New)
 
-## `<TutoShowcase />` Props
-
-| Prop                     | Type                  | Default            | Description                        |
-| ------------------------ | --------------------- | ------------------ | ---------------------------------- |
-| `title`                  | `ReactNode`           | —                  | Title element (supports JSX & RTL) |
-| `description`            | `string \| ReactNode` | —                  | Description text                   |
-| `buttonText`             | `string`              | `"GOT IT"`         | CTA button label                   |
-| `buttonTextStyle`        | `TextStyle`           | —                  | Custom style for CTA text          |
-| `buttonContainerStyle`   | `ViewStyle`           | —                  | Custom style for CTA container     |
-| `overlayBackgroundColor` | `string`              | `rgba(0,0,0,0.78)` | Background dim color               |
-| `onGotIt`                | `() => void`          | —                  | Called when user presses CTA       |
-| `lottie`                 | `ReactElement`        | —                  | Lottie animation above target      |
+The Lottie animation is now positioned **relative to the full screen**, not the spotlight.
 
 ---
 
-# 🎛 Ref API (Controller)
-
-Returned via:
+## 🔹 Available placements
 
-```ts
-const tutoRef = useRef<TutoShowcaseHandle>(null);
 ```
-
-Then:
-
-```ts
-tutoRef.current?.on(targetRef)
+top-left
+top-center
+top-right
+bottom-left
+bottom-center
+bottom-right
+center
 ```
 
-### Methods
-
-| Method                                 | Description                                  |
-| -------------------------------------- | -------------------------------------------- |
-| `on(ref)`                              | Select target element                        |
-| `show()`                               | Show the spotlight                           |
-| `dismiss()`                            | Hide the overlay                             |
-| `addCircle(ratio?)`                    | Add circle spotlight                         |
-| `addRoundRect(ratio?, radius?, opts?)` | Add rounded-rect spotlight                   |
-| `displaySwipableLeft()`                | Show left gesture hint                       |
-| `displaySwipableRight()`               | Show right gesture hint                      |
-| `displayScrollable()`                  | Show scroll gesture hint                     |
-| `withBorder()`                         | Add border around spotlight                  |
-| `onClick(cb)`                          | Make spotlight clickable                     |
-| `showOnce(key)`                        | Show once only (persistent via AsyncStorage) |
-| `resetShowOnce(key)`                   | Clear “show once” key                        |
-| `isShowOnce(key)`                      | Check stored key                             |
-
----
-
-# 🎬 Lottie Support
+## 🔹 Example
 
 ```tsx
 <TutoShowcase
@@ -174,25 +114,75 @@ tutoRef.current?.on(targetRef)
     <LottieView
       source={require('./hand.json')}
       style={{ width: 120, height: 120 }}
-      autoPlay
-      loop
     />
   }
+  lottiePlacement="top-right"
+  lottieOffset={{ dx: -20, dy: 10 }}
 />
 ```
 
-Lottie will automatically be positioned above the target highlight.
+---
+
+# 🧩 Props
+
+## `<TutoShowcase />`
+
+| Prop                     | Type                           | Default            | Description             |
+| ------------------------ | ------------------------------ | ------------------ | ----------------------- |
+| `title`                  | `ReactNode`                    | —                  | Title JSX               |
+| `description`            | `string \| ReactNode`          | —                  | Description text        |
+| `buttonText`             | `string`                       | `"GOT IT"`         | CTA label               |
+| `buttonTextStyle`        | `TextStyle`                    | —                  | Style for CTA text      |
+| `buttonContainerStyle`   | `ViewStyle`                    | —                  | Style for CTA button    |
+| `overlayBackgroundColor` | `string`                       | `rgba(0,0,0,0.78)` | Dim overlay color       |
+| `onGotIt`                | `() => void`                   | —                  | Called when CTA pressed |
+| `lottie`                 | `ReactElement`                 | —                  | Lottie animation        |
+| **`lottiePlacement`**    | `"top-left" \| ...`            | `"top-center"`     | ⭐ Full-screen placement |
+| **`lottieOffset`**       | `{ dx?: number; dy?: number }` | `{}`               | Extra offset            |
 
 ---
 
-# 🎨 Customizing Button Style
+# 🎛 Ref API
+
+```ts
+const tutoRef = useRef<TutoShowcaseHandle>(null);
+```
+
+| Method                                 | Description                   |
+| -------------------------------------- | ----------------------------- |
+| `on(ref)`                              | Select target element         |
+| `addCircle(ratio?)`                    | Add circle spotlight          |
+| `addRoundRect(ratio?, radius?, opts?)` | Add rounded spotlight         |
+| `withBorder()`                         | Add border                    |
+| `displaySwipableLeft()`                | Gesture hint                  |
+| `displaySwipableRight()`               | Gesture hint                  |
+| `displayScrollable()`                  | Gesture hint                  |
+| `onClick(cb)`                          | Capture taps inside spotlight |
+| `show()`                               | Show spotlight immediately    |
+| `showOnce(key)`                        | Show once (AsyncStorage)      |
+| `resetShowOnce(key)`                   | Clear stored key              |
+| `isShowOnce(key)`                      | Check if key shown            |
+
+---
+
+# 🗂 Show Once Logic
+
+```tsx
+tutoRef.current
+  ?.on(boxRef)
+  .addCircle()
+  .showOnce('first-time');
+```
+
+---
+
+# 🎨 Button Customization
 
 ```tsx
 <TutoShowcase
   buttonContainerStyle={{
     backgroundColor: '#FFD700',
-    paddingVertical: 10,
-    borderRadius: 8,
+    borderRadius: 10,
   }}
   buttonTextStyle={{
     color: '#000',
@@ -203,55 +193,35 @@ Lottie will automatically be positioned above the target highlight.
 
 ---
 
-# ⚙ Spotlight Shape Options
+# 📐 Spotlight Options
 
-### Circle Spotlight
+### Circle
 
-```ts
+```tsx
 .on(ref)
-.addCircle(1.2) // ratio
+.addCircle(1.3)
 .show()
 ```
 
-### Rounded Rectangle Spotlight
+### Rounded Rectangle
 
-```ts
+```tsx
 .on(ref)
-.addRoundRect(1.1, 20, { pad: 30, dx: 0, dy: 0 })
+.addRoundRect(1.1, 20, { pad: 30 })
 .show()
 ```
 
 ---
 
-# 🗂 Show Once Logic
-
-```ts
-tutoRef.current
-  ?.on(someRef)
-  .addCircle()
-  .showOnce('home-feature');
-```
-
-Key stored automatically in AsyncStorage → won’t show again.
-
----
-
-# 📦 TypeScript Support
+# 🎥 Demo Videos
 
-Bundled `.d.ts` typings included automatically:
+### 📱 iOS
 
-```ts
-import type { TutoShowcaseHandle } from 'react-native-tuto-showcase';
-```
+[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](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)
 
----
-
-# 📐 Important Notes
+### 🤖 Android
 
-* Must wrap elements you spotlight with a `ref`
-* Uses `measureInWindow` → works inside ScrollView, Tabs, Modals, etc.
-* Overlay is drawn using **react-native-svg**
-* Fully RTL-compatible
+[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](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)
 
 ---
 
@@ -259,5 +229,4 @@ import type { TutoShowcaseHandle } from 'react-native-tuto-showcase';
 
 MIT © **Ahmed Mohamed Ali Ali Hegazy**
 
----
-
+---

package/dist/components/LottieAboveTarget.d.ts

@@ -1,6 +1,18 @@
 import React from 'react';
 import { AnyShape } from '../types/shapes';
-export default function LottieAboveTarget({ shapes, lottie, }: {
+export type LottiePlacement = 'top-left' | 'top-right' | 'top-center' | 'bottom-left' | 'bottom-right' | 'bottom-center' | 'center';
+type Offset = {
+    dx?: number;
+    dy?: number;
+};
+type Props = {
     shapes: AnyShape[];
     lottie: React.ReactElement<any>;
-}): import("react/jsx-runtime").JSX.Element | null;
+    overlayWidth: number;
+    overlayHeight: number;
+    placement?: LottiePlacement;
+    offset?: Offset;
+};
+export default function LottieAboveTarget({ shapes, lottie, overlayWidth, overlayHeight, placement, // 👈 الديفولت: فوق في النص بالنسبة للشاشة كلها
+offset, }: Props): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/components/LottieAboveTarget.js

@@ -1,17 +1,56 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import React from 'react';
 import { View, StyleSheet } from 'react-native';
-export default function LottieAboveTarget({ shapes, lottie, }) {
-    if (!lottie || shapes.length === 0)
+const PADDING_H = 24;
+const PADDING_V = 32;
+export default function LottieAboveTarget({ shapes, lottie, overlayWidth, overlayHeight, placement = 'top-center', // 👈 الديفولت: فوق في النص بالنسبة للشاشة كلها
+offset, }) {
+    if (!lottie)
         return null;
-    const focus = shapes[shapes.length - 1];
     const layout = StyleSheet.flatten(lottie.props?.style) || {};
     const lw = layout.width ?? 100;
     const lh = layout.height ?? 100;
-    const cx = focus.cx;
-    const topOfHole = focus.type === 'circle' ? focus.cy - focus.r : focus.y;
-    const top = topOfHole - lh + 50;
-    const left = cx - lw / 2;
+    let top = 0;
+    let left = 0;
+    switch (placement) {
+        case 'top-left':
+            top = PADDING_V;
+            left = PADDING_H;
+            break;
+        case 'top-right':
+            top = PADDING_V;
+            left = overlayWidth - lw - PADDING_H;
+            break;
+        case 'top-center':
+            top = PADDING_V;
+            left = (overlayWidth - lw) / 2;
+            break;
+        case 'bottom-left':
+            top = overlayHeight - lh - PADDING_V;
+            left = PADDING_H;
+            break;
+        case 'bottom-right':
+            top = overlayHeight - lh - PADDING_V;
+            left = overlayWidth - lw - PADDING_H;
+            break;
+        case 'bottom-center':
+            top = overlayHeight - lh - PADDING_V;
+            left = (overlayWidth - lw) / 2;
+            break;
+        case 'center':
+            top = (overlayHeight - lh) / 2;
+            left = (overlayWidth - lw) / 2;
+            break;
+        default:
+            top = PADDING_V;
+            left = (overlayWidth - lw) / 2;
+            break;
+    }
+    // ✅ اختياري: إزاحة إضافية
+    if (offset?.dx)
+        left += offset.dx;
+    if (offset?.dy)
+        top += offset.dy;
     return (_jsx(View, { pointerEvents: "none", style: [
             styles.container,
             { top, left, width: lw, height: lh },

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import React from 'react';
+import { LottiePlacement } from './components/LottieAboveTarget';
 export type TutoShowcaseHandle = {
     on: (r: any) => any;
     show: () => void;
@@ -7,5 +8,20 @@ export type TutoShowcaseHandle = {
     isShowOnce: (key: string) => boolean;
     resetShowOnce: (key: string) => void;
 };
-declare const TutoShowcase: React.ForwardRefExoticComponent<Omit<any, "ref"> & React.RefAttributes<TutoShowcaseHandle>>;
+type TutoShowcaseProps = {
+    title?: React.ReactNode;
+    description?: React.ReactNode;
+    buttonText?: string;
+    buttonTextStyle?: any;
+    buttonContainerStyle?: any;
+    overlayBackgroundColor?: string;
+    onGotIt?: () => void;
+    lottie?: React.ReactElement<any> | null;
+    lottiePlacement?: LottiePlacement;
+    lottieOffset?: {
+        dx?: number;
+        dy?: number;
+    };
+};
+declare const TutoShowcase: React.ForwardRefExoticComponent<TutoShowcaseProps & React.RefAttributes<TutoShowcaseHandle>>;
 export default TutoShowcase;

package/dist/index.js

@@ -11,7 +11,8 @@ 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 TutoShowcase = forwardRef(function Tuto({ title, description, buttonText = 'GOT IT', buttonTextStyle, buttonContainerStyle, overlayBackgroundColor, onGotIt, lottie, }, ref) {
+const TutoShowcase = forwardRef(function Tuto({ title, description, buttonText = 'GOT IT', buttonTextStyle, buttonContainerStyle, overlayBackgroundColor, onGotIt, lottie, lottiePlacement, // 👈 خدناه من props
+lottieOffset, }, ref) {
     // -------- Hooks يجب أن تكون في الأعلى وبنفس الترتيب دائماً --------
     const [visible, setVisible] = useState(false);
     const [bgColor, setBgColor] = useState(overlayBackgroundColor || DEFAULT_BG);
@@ -84,7 +85,7 @@ const TutoShowcase = forwardRef(function Tuto({ title, description, buttonText =
     // ✅ الشرط هنا بعد كل الـ 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 }), (title || description) && (_jsx(ContentSection, { title: title, description: description, buttonText: buttonText, buttonTextStyle: buttonTextStyle, buttonContainerStyle: buttonContainerStyle, coords: coords, onPress: () => {
+    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 })] }) }) }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-tuto-showcase",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Customizable tutorial / spotlight overlay for React Native (onboarding, feature tours, coachmarks).",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,18 +26,18 @@
   ],
   "author": "Ahmed Mohamed Ali Ali Hegazy",
   "license": "MIT",
+  "packageManager": "yarn@3.6.4+sha512.e70835d4d6d62c07be76b3c1529cb640c7443f0fe434ef4b6478a5a399218cbaf1511b396b3c56eb03bc86424cff2320f6167ad2fde273aa0df6e60b7754029f",
   "peerDependencies": {
+    "@react-native-async-storage/async-storage": ">=1.17.0",
     "react": ">=18.0.0",
-    "react-native": ">=0.72.0"
-  },
-  "dependencies": {
-    "@react-native-async-storage/async-storage": "^1.23.0",
-    "react-native-svg": "^13.14.0"
+    "react-native": ">=0.72.0",
+    "react-native-svg": ">=13.0.0"
   },
-  "packageManager": "yarn@3.6.4+sha512.e70835d4d6d62c07be76b3c1529cb640c7443f0fe434ef4b6478a5a399218cbaf1511b396b3c56eb03bc86424cff2320f6167ad2fde273aa0df6e60b7754029f",
   "devDependencies": {
+    "@react-native-async-storage/async-storage": "^1.23.0",
     "@types/react": "^19.2.7",
     "@types/react-native": "^0.72.8",
+    "react-native-svg": "^13.14.0",
     "typescript": "^5.9.3"
   }
 }