react-native-tuto-showcase 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,263 @@
+# 📘 **react-native-tuto-showcase**
+
+### 🔦 A fully customizable Spotlight / Tutorial / Coachmark overlay for React Native
+
+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"
+/>
+
+---
+
+# ✨ Features
+
+* 🎯 Highlight any UI element using **circle or rounded-rectangle 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**
+
+* ⚡ Supports React Native 0.72+
+
+---
+
+# 📦 Installation
+
+```sh
+npm install react-native-tuto-showcase
+# or
+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**
+
+```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() {
+  const tutoRef = useRef<TutoShowcaseHandle>(null);
+  const boxRef = useRef<View>(null);
+
+  return (
+    <>
+      <TutoShowcase
+        ref={tutoRef}
+        title={<Text style={{ color: '#fff', fontSize: 22 }}>ترتيب الأقسام</Text>}
+        description={
+          'يمكنك سحب هذا القسم لأعلى أو لأسفل لتغيير ترتيبه في الصفحة.\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 }}>
+        <Text>Drag Me</Text>
+      </View>
+
+      <Pressable
+        onPress={() => {
+          tutoRef.current
+            ?.on(boxRef)
+            .addRoundRect()
+            .withBorder()
+            .showOnce('highlight-box');
+        }}>
+        <Text>Start Tutorial</Text>
+      </Pressable>
+    </>
+  );
+}
+```
+
+---
+
+# 🧩 API Documentation
+
+## `<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      |
+
+---
+
+# 🎛 Ref API (Controller)
+
+Returned via:
+
+```ts
+const tutoRef = useRef<TutoShowcaseHandle>(null);
+```
+
+Then:
+
+```ts
+tutoRef.current?.on(targetRef)
+```
+
+### 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
+
+```tsx
+<TutoShowcase
+  ref={tutoRef}
+  lottie={
+    <LottieView
+      source={require('./hand.json')}
+      style={{ width: 120, height: 120 }}
+      autoPlay
+      loop
+    />
+  }
+/>
+```
+
+Lottie will automatically be positioned above the target highlight.
+
+---
+
+# 🎨 Customizing Button Style
+
+```tsx
+<TutoShowcase
+  buttonContainerStyle={{
+    backgroundColor: '#FFD700',
+    paddingVertical: 10,
+    borderRadius: 8,
+  }}
+  buttonTextStyle={{
+    color: '#000',
+    fontWeight: 'bold',
+  }}
+/>
+```
+
+---
+
+# ⚙ Spotlight Shape Options
+
+### Circle Spotlight
+
+```ts
+.on(ref)
+.addCircle(1.2) // ratio
+.show()
+```
+
+### Rounded Rectangle Spotlight
+
+```ts
+.on(ref)
+.addRoundRect(1.1, 20, { pad: 30, dx: 0, dy: 0 })
+.show()
+```
+
+---
+
+# 🗂 Show Once Logic
+
+```ts
+tutoRef.current
+  ?.on(someRef)
+  .addCircle()
+  .showOnce('home-feature');
+```
+
+Key stored automatically in AsyncStorage → won’t show again.
+
+---
+
+# 📦 TypeScript Support
+
+Bundled `.d.ts` typings included automatically:
+
+```ts
+import type { TutoShowcaseHandle } from 'react-native-tuto-showcase';
+```
+
+---
+
+# 📐 Important Notes
+
+* 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
+
+---
+
+# 📝 License
+
+MIT © **Ahmed Mohamed Ali Ali Hegazy**
+
+---
+

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "react-native-tuto-showcase",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Customizable tutorial / spotlight overlay for React Native (onboarding, feature tours, coachmarks).",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "source": "src/index.tsx",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsc"
   },
@@ -34,5 +36,4 @@
     "@types/react-native": "^0.72.8",
     "typescript": "^5.9.3"
   }
-  
 }