react-native-tuto-showcase 1.0.2 → 1.0.4

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-tuto-showcase",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Customizable tutorial / spotlight overlay for React Native (onboarding, feature tours, coachmarks).",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,6 +8,10 @@
   "files": [
     "dist"
   ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ahmedhegazydev/react-native-tuto-showcase.git"
+  },
   "scripts": {
     "build": "tsc"
   },