react-native-tuto-showcase 1.0.5 β†’ 1.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +186 -79
  3. package/package.json +21 -2
package/LICENSE CHANGED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Ahmed Mohamed Ali Ali Hegazy
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,48 +1,82 @@
1
- # πŸ“˜ **react-native-tuto-showcase**
1
+ # πŸ”¦ **react-native-tuto-showcase**
2
2
 
3
- ### πŸ”¦ A fully customizable Spotlight / Tutorial / Coachmark overlay for React Native
3
+ **Fully Customizable Spotlight / Tutorial / Coachmark Overlay for React Native β€” Perfect for Onboarding, Feature Discovery & Guided Tours**
4
4
 
5
- Perfect for onboarding flows, feature tours, highlighting UI elements, and guiding users interactively.
5
+ [![npm version](https://img.shields.io/npm/v/react-native-tuto-showcase.svg)](https://www.npmjs.com/package/react-native-tuto-showcase)
6
+ [![license](https://img.shields.io/npm/l/react-native-tuto-showcase.svg)](https://github.com/ahmedhegazydev/react-native-tuto-showcase/blob/master/LICENSE)
7
+ ![platforms](https://img.shields.io/badge/platforms-ios%20%7C%20android-lightgrey.svg)
8
+ ![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue.svg)
9
+ ![React Native](https://img.shields.io/badge/React%20Native-%5E0.72%2B-61dafb.svg)
10
+
11
+ A lightweight yet powerful **spotlight / walkthrough / coachmark** component for React Native that helps you:
12
+
13
+ * Guide users through **onboarding flows**
14
+ * Highlight **new features**
15
+ * Explain **complex UI**
16
+ * Drive **feature adoption & discovery**
6
17
 
7
18
  Now with **full-screen Lottie placement** + **custom offsets**.
8
19
 
9
20
  ---
10
21
 
11
- # ✨ Features
22
+ ## ✨ Features
23
+
24
+ * 🎯 **Highlight any UI element**
25
+
26
+ * Circle or rounded-rectangle **spotlight**
27
+ * Uses `measureInWindow` to auto-calc coordinates
28
+ * πŸ“ **Smart positioning**
29
+
30
+ * Spotlight automatically tracks the referenced `ref`
31
+ * 🧠 **Show-once logic (AsyncStorage)**
32
+
33
+ * `.showOnce(key)` / `.resetShowOnce(key)` / `.isShowOnce(key)`
34
+ * 🎞 **Lottie Animations β€” Full-Screen Placement**
12
35
 
13
- * 🎯 Highlight any UI element with **Circle / RoundRect** spotlight
14
- * πŸ“ Auto-calculated spotlight position using `measureInWindow`
15
- * πŸ” Show-once logic (AsyncStorage)
16
- * 🎞 **Lottie Animations with full-screen positioning**
36
+ * Place the animation relative to the **screen**, not the spotlight
37
+ * Built-in placements:
17
38
 
18
- * `top-left`, `top-right`, `top-center`
19
- * `bottom-left`, `bottom-right`, `bottom-center`
20
- * `center`
21
- * * `lottieOffset={{dx, dy}}`
22
- * πŸ“¦ Multiple spots on one screen
23
- * βœ‹ Gesture hints (swipe / scroll)
24
- * 🎨 Fully customizable:
39
+ * `top-left`, `top-center`, `top-right`
40
+ * `bottom-left`, `bottom-center`, `bottom-right`
41
+ * `center`
42
+ * Fine-tune with `lottieOffset={{ dx, dy }}`
43
+ * πŸ“¦ **Multiple spots on one screen**
25
44
 
26
- * Colors
27
- * Button style
28
- * Fonts
29
- * Overlay background
30
- * πŸ“± Works on **iOS & Android**
31
- * ⚑ Supports React Native 0.72+
45
+ * Chain calls on the same ref (circle / rect / gestures)
46
+ * βœ‹ **Gesture hints**
47
+
48
+ * `.displaySwipableLeft()`
49
+ * `.displaySwipableRight()`
50
+ * `.displayScrollable()`
51
+ * 🎨 **Fully customizable UI**
52
+
53
+ * Overlay color
54
+ * Button container & text style
55
+ * Custom title & description JSX
56
+ * Works great with your design system / theming
57
+ * πŸ“± **Cross-platform**
58
+
59
+ * iOS & Android
60
+ * ⚑ **Modern RN stack**
61
+
62
+ * React Native **0.72+**
63
+ * TypeScript-friendly API
32
64
 
33
65
  ---
34
66
 
35
- # πŸ“¦ Installation
67
+ ## πŸ“¦ Installation
36
68
 
37
- ```sh
69
+ ```bash
38
70
  npm install react-native-tuto-showcase
39
- # or
71
+ # OR
40
72
  yarn add react-native-tuto-showcase
41
73
  ```
42
74
 
75
+ No extra native setup required beyond your standard React Native project.
76
+
43
77
  ---
44
78
 
45
- # πŸš€ Basic Usage
79
+ ## πŸš€ Basic Usage
46
80
 
47
81
  ```tsx
48
82
  import React, { useRef } from 'react';
@@ -65,7 +99,10 @@ export default function Home() {
65
99
  buttonText="ΨͺΩ…Ψ§Ω…"
66
100
  />
67
101
 
68
- <View ref={boxRef} style={{ marginTop: 120, padding: 20, backgroundColor: '#eee' }}>
102
+ <View
103
+ ref={boxRef}
104
+ style={{ marginTop: 120, padding: 20, backgroundColor: '#eee' }}
105
+ >
69
106
  <Text>Drag Me</Text>
70
107
  </View>
71
108
 
@@ -87,15 +124,13 @@ export default function Home() {
87
124
 
88
125
  ---
89
126
 
90
- # 🎞 Lottie Placement (New)
127
+ ## 🎞 Lottie Placement (New)
91
128
 
92
- The Lottie animation is now positioned **relative to the full screen**, not the spotlight.
129
+ 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.
93
130
 
94
- ---
95
-
96
- ## πŸ”Ή Available placements
131
+ ### πŸ”Ή Available placements
97
132
 
98
- ```
133
+ ```text
99
134
  top-left
100
135
  top-center
101
136
  top-right
@@ -105,15 +140,19 @@ bottom-right
105
140
  center
106
141
  ```
107
142
 
108
- ## πŸ”Ή Example
143
+ ### πŸ”Ή Example
109
144
 
110
145
  ```tsx
146
+ import LottieView from 'lottie-react-native';
147
+
111
148
  <TutoShowcase
112
149
  ref={tutoRef}
113
150
  lottie={
114
151
  <LottieView
115
152
  source={require('./hand.json')}
116
153
  style={{ width: 120, height: 120 }}
154
+ autoPlay
155
+ loop
117
156
  />
118
157
  }
119
158
  lottiePlacement="top-right"
@@ -123,110 +162,178 @@ center
123
162
 
124
163
  ---
125
164
 
126
- # 🧩 Props
165
+ ## 🧩 `<TutoShowcase />` Props
127
166
 
128
- ## `<TutoShowcase />`
167
+ | Prop | Type | Default | Description |
168
+ | ------------------------ | ------------------------------ | ------------------ | ------------------------------------ |
169
+ | `title` | `ReactNode` | β€” | Title JSX (text, icons, etc.) |
170
+ | `description` | `string \| ReactNode` | β€” | Description text or custom JSX |
171
+ | `buttonText` | `string` | `"GOT IT"` | CTA button label |
172
+ | `buttonTextStyle` | `TextStyle` | β€” | Style for CTA text |
173
+ | `buttonContainerStyle` | `ViewStyle` | β€” | Style for CTA button wrapper |
174
+ | `overlayBackgroundColor` | `string` | `rgba(0,0,0,0.78)` | Dim background overlay color |
175
+ | `onGotIt` | `() => void` | β€” | Callback when CTA is pressed |
176
+ | `lottie` | `ReactElement` | β€” | Lottie animation component |
177
+ | `lottiePlacement` | `"top-left" \| ...` | `"top-center"` | Full-screen placement of the Lottie |
178
+ | `lottieOffset` | `{ dx?: number; dy?: number }` | `{}` | Extra offset applied after placement |
129
179
 
130
- | Prop | Type | Default | Description |
131
- | ------------------------ | ------------------------------ | ------------------ | ----------------------- |
132
- | `title` | `ReactNode` | β€” | Title JSX |
133
- | `description` | `string \| ReactNode` | β€” | Description text |
134
- | `buttonText` | `string` | `"GOT IT"` | CTA label |
135
- | `buttonTextStyle` | `TextStyle` | β€” | Style for CTA text |
136
- | `buttonContainerStyle` | `ViewStyle` | β€” | Style for CTA button |
137
- | `overlayBackgroundColor` | `string` | `rgba(0,0,0,0.78)` | Dim overlay color |
138
- | `onGotIt` | `() => void` | β€” | Called when CTA pressed |
139
- | `lottie` | `ReactElement` | β€” | Lottie animation |
140
- | **`lottiePlacement`** | `"top-left" \| ...` | `"top-center"` | ⭐ Full-screen placement |
141
- | **`lottieOffset`** | `{ dx?: number; dy?: number }` | `{}` | Extra offset |
180
+ > πŸ’‘ You can pass any **custom JSX** for `title` / `description` to plug into your design system (e.g. `Text`, `Heading`, `Icon + Text`, etc.)
142
181
 
143
182
  ---
144
183
 
145
- # πŸŽ› Ref API
184
+ ## πŸŽ› Ref API
146
185
 
147
186
  ```ts
187
+ import { TutoShowcaseHandle } from 'react-native-tuto-showcase';
188
+
148
189
  const tutoRef = useRef<TutoShowcaseHandle>(null);
149
190
  ```
150
191
 
151
- | Method | Description |
152
- | -------------------------------------- | ----------------------------- |
153
- | `on(ref)` | Select target element |
154
- | `addCircle(ratio?)` | Add circle spotlight |
155
- | `addRoundRect(ratio?, radius?, opts?)` | Add rounded spotlight |
156
- | `withBorder()` | Add border |
157
- | `displaySwipableLeft()` | Gesture hint |
158
- | `displaySwipableRight()` | Gesture hint |
159
- | `displayScrollable()` | Gesture hint |
160
- | `onClick(cb)` | Capture taps inside spotlight |
161
- | `show()` | Show spotlight immediately |
162
- | `showOnce(key)` | Show once (AsyncStorage) |
163
- | `resetShowOnce(key)` | Clear stored key |
164
- | `isShowOnce(key)` | Check if key shown |
192
+ | Method | Description |
193
+ | -------------------------------------- | ---------------------------------------------- |
194
+ | `on(ref)` | Attach spotlight to a target element `ref` |
195
+ | `addCircle(ratio?)` | Add **circular** spotlight |
196
+ | `addRoundRect(ratio?, radius?, opts?)` | Add **rounded-rectangle** spotlight |
197
+ | `withBorder()` | Add border around spotlight |
198
+ | `displaySwipableLeft()` | Show swipe-left gesture hint |
199
+ | `displaySwipableRight()` | Show swipe-right gesture hint |
200
+ | `displayScrollable()` | Show scroll gesture hint |
201
+ | `onClick(cb)` | Capture taps inside spotlight area |
202
+ | `show()` | Show tutorial immediately |
203
+ | `showOnce(key)` | Show only once per key (saved in AsyncStorage) |
204
+ | `resetShowOnce(key)` | Clear stored key; show again next time |
205
+ | `isShowOnce(key)` | Check if a specific key has already been shown |
165
206
 
166
207
  ---
167
208
 
168
- # πŸ—‚ Show Once Logic
209
+ ## πŸ—‚ Show Once Logic
210
+
211
+ Use `showOnce(key)` to avoid spamming users with the same tutorial:
169
212
 
170
213
  ```tsx
171
214
  tutoRef.current
172
215
  ?.on(boxRef)
173
216
  .addCircle()
174
- .showOnce('first-time');
217
+ .showOnce('first-time-highlight');
218
+ ```
219
+
220
+ To reset:
221
+
222
+ ```tsx
223
+ tutoRef.current?.resetShowOnce('first-time-highlight');
224
+ ```
225
+
226
+ To check:
227
+
228
+ ```tsx
229
+ const alreadyShown = await tutoRef.current?.isShowOnce('first-time-highlight');
175
230
  ```
176
231
 
177
232
  ---
178
233
 
179
- # 🎨 Button Customization
234
+ ## 🎨 Button & Overlay Customization
180
235
 
181
236
  ```tsx
182
237
  <TutoShowcase
238
+ overlayBackgroundColor="rgba(15, 23, 42, 0.85)" // slate-like
183
239
  buttonContainerStyle={{
184
240
  backgroundColor: '#FFD700',
185
- borderRadius: 10,
241
+ borderRadius: 999,
242
+ paddingHorizontal: 24,
243
+ paddingVertical: 10,
186
244
  }}
187
245
  buttonTextStyle={{
188
246
  color: '#000',
189
247
  fontWeight: 'bold',
248
+ fontSize: 16,
190
249
  }}
191
250
  />
192
251
  ```
193
252
 
194
253
  ---
195
254
 
196
- # πŸ“ Spotlight Options
255
+ ## πŸ“ Spotlight Examples
197
256
 
198
257
  ### Circle
199
258
 
200
259
  ```tsx
201
- .on(ref)
202
- .addCircle(1.3)
203
- .show()
260
+ tutoRef.current
261
+ ?.on(boxRef)
262
+ .addCircle(1.3) // 1.0 = tight, >1 expands radius
263
+ .show();
204
264
  ```
205
265
 
206
266
  ### Rounded Rectangle
207
267
 
208
268
  ```tsx
209
- .on(ref)
210
- .addRoundRect(1.1, 20, { pad: 30 })
211
- .show()
269
+ tutoRef.current
270
+ ?.on(boxRef)
271
+ .addRoundRect(1.1, 20, { pad: 30 }) // ratio, corner radius, extra padding
272
+ .show();
212
273
  ```
213
274
 
214
275
  ---
215
276
 
216
- # πŸŽ₯ Demo Videos
277
+ ## πŸŽ₯ Demo Videos
217
278
 
218
279
  ### πŸ“± iOS
219
280
 
220
- [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)
281
+ [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)
221
282
 
222
283
  ### πŸ€– Android
223
284
 
224
- [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)
285
+ [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)
286
+
287
+ ---
288
+
289
+ ## 🧠 Typical Use Cases
290
+
291
+ * App **onboarding** & first-time user experience
292
+ * Feature discovery (β€œWhat’s new” walkthroughs)
293
+ * Highlighting **FAB buttons**, menus, tabs, drawers
294
+ * Teaching users **drag & drop** / **reorder** interactions
295
+ * Coachmarks for:
296
+
297
+ * Dashboards
298
+ * Settings screens
299
+ * Maps & complex UI
300
+ * Internal QA / UX testing sessions
301
+
302
+ ---
303
+
304
+ ## πŸ›  Troubleshooting
305
+
306
+ | Issue | Hint |
307
+ | ------------------------------- | ------------------------------------------------------------ |
308
+ | Spotlight not aligned correctly | Ensure the target has a `ref` and is rendered on screen |
309
+ | Nothing shows up | Check `tutoRef.current` is not `null` before calling methods |
310
+ | `showOnce` not working | Verify AsyncStorage is properly linked & no key collisions |
311
+ | Lottie is cut or off-screen | Adjust `lottiePlacement` + `lottieOffset` |
312
+
313
+ ---
314
+
315
+ ## πŸ—Ί Roadmap
316
+
317
+ * βœ… Multiple-step walkthrough sequences
318
+ * βœ… Better gesture presets
319
+ * πŸ”œ RTL-aware layouts
320
+ * πŸ”œ Built-in themes (light / dark)
321
+ * πŸ”œ Auto β€œNext / Previous” between spots
322
+ * πŸ”œ Expo Snack examples
323
+
324
+ > PRs & feature requests are very welcome ✨
225
325
 
226
326
  ---
227
327
 
228
- # πŸ“ License
328
+ ## πŸ‘€ Author
329
+
330
+ Built with ❀️ by **Ahmed Hegazy**
331
+
332
+ * πŸ“§ [ahmedmhegazy.eg@gmail.com](mailto:ahmedmhegazy.eg@gmail.com)
333
+ * πŸ™ GitHub: [@ahmedhegazydev](https://github.com/ahmedhegazydev)
334
+
335
+ ---
229
336
 
230
- MIT Β© **Ahmed Mohamed Ali Ali Hegazy**
337
+ ## πŸ“„ License
231
338
 
232
- ---
339
+ MIT Β© **Ahmed Mohamed Ali Ali Hegazy**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "react-native-tuto-showcase",
3
- "version": "1.0.5",
3
+ "version": "1.0.7",
4
4
  "description": "Customizable tutorial / spotlight overlay for React Native (onboarding, feature tours, coachmarks).",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -22,7 +22,26 @@
22
22
  "spotlight",
23
23
  "showcase",
24
24
  "coachmark",
25
- "overlay"
25
+ "overlay",
26
+ "react native tutorial",
27
+ "react native onboarding",
28
+ "react native coach marks",
29
+ "react native walkthrough",
30
+ "react native spotlight",
31
+ "react native highlight view",
32
+ "react native feature discovery",
33
+ "react native guided tour",
34
+ "react native tooltip overlay",
35
+ "react native help overlay",
36
+ "react native lottie overlay",
37
+ "react native interactive tutorial",
38
+ "react native drag reorder tutorial",
39
+ "react native product tour",
40
+ "react native showcase",
41
+ "react native hint",
42
+ "react native gesture hint",
43
+ "react native ux onboarding",
44
+ "react native step by step tutorial"
26
45
  ],
27
46
  "author": "Ahmed Mohamed Ali Ali Hegazy",
28
47
  "license": "MIT",