react-native-lumen 1.1.1 → 1.1.2

package/LICENSE

@@ -1,20 +1,20 @@
-MIT License
-
-Copyright (c) 2026 thedev204
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 thedev204
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,10 +1,39 @@
-# React Native Lumen 💡
+<p align="center">
+  <div align="center">
+    <a href="https://www.npmjs.com/package/react-native-lumen">
+      <img src="https://img.shields.io/npm/v/react-native-lumen.svg" alt="npm version" />
+    </a>
+    <a href="https://www.npmjs.com/package/react-native-lumen">
+      <img src="https://img.shields.io/npm/dm/react-native-lumen.svg?colorB=007ec6" alt="npm downloads" />
+    </a>
+    <a href="https://github.com/thedev204/react-native-lumen/blob/main/LICENSE">
+      <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="license" />
+    </a>
+  </div>
+  <div align="center">
+    <a href="https://github.com/expo/expo">
+      <img src="https://img.shields.io/badge/Runs%20with%20Expo-000.svg?style=flat&logo=EXPO&labelColor=ffffff&logoColor=000" alt="runs with expo" />
+    </a>
+    <a href="https://github.com/thedev204/react-native-lumen/issues">
+      <img src="https://img.shields.io/github/issues/thedev204/react-native-lumen.svg" alt="github issues" />
+    </a>
+    <a href="https://semver.org/spec/v2.0.0.html">
+      <img src="https://img.shields.io/badge/semver-2.0.0-e10079.svg" alt="semver" />
+    </a>
+  </div>
+</p>
+
+<br/>
 
-[![npm version](https://img.shields.io/npm/v/react-native-lumen.svg)](https://www.npmjs.com/package/react-native-lumen)
+<h1 align="center">React Native Lumen 💡</h1>
 
-> A high-performance, fully customizable app tour library for React Native, powered by Reanimated 3.
+<p align="center">
+  A high-performance, fully customizable app tour library for React Native, powered by Reanimated 3.
+</p>
 
-![Banner](./assets/banner.png)
+<p align="center">
+  <img src="./assets/banner.png" alt="React Native Lumen Banner" />
+</p>
 
 ## Demo
 
@@ -13,27 +42,16 @@
   <img src="./assets/showcase2.gif" width="220" alt="App Tour Demo" />
 </p>
 
-## Features
-
-- ⚡ **High Performance**: Built with `react-native-reanimated` worklets for 60fps animations.
-- 🎨 **Fully Customizable**: Custom Renderers for tooltips, customizable shapes, and backdrops.
-- 🌟 **Glow Effects**: Beautiful, customizable glow effects around your highlighted elements.
-- 📱 **Expo Compatible**: Works seamlessly with Expo and bare React Native projects.
-- 🤸 **Smooth Transitions**: Fluid morphing animations between steps.
-- ✨ **Animation Presets**: Ships with beautiful bouncy, gentle, and snappy spring presets.
-- 📜 **Auto Scrolling**: Automatically scrolls to next steps.
-- 👆 **Interaction Control**: Choose to block or allow interactions with the underlying app.
-- 🔒 **Step Enforcement**: Gate step progression with `required` and `completed` props.
-- 📱 **Multi-Screen Tours**: Seamlessly run tours across multiple screens/tabs with screen-grouped step ordering.
+---
 
 ## Requirements
 
-This library relies on strict peer dependencies to ensure performance:
-
-- `react-native` >= 0.70.0
-- `react-native-reanimated` >= 3.0.0
-- `react-native-svg` >= 12.0.0
-- `react-native-gesture-handler` >= 2.0.0
+| Package                        | Version   |
+| :----------------------------- | :-------- |
+| `react-native`                 | >= 0.70.0 |
+| `react-native-reanimated`      | >= 3.0.0  |
+| `react-native-svg`             | >= 12.0.0 |
+| `react-native-gesture-handler` | >= 2.0.0  |
 
 ## Installation
 
@@ -41,730 +59,68 @@ This library relies on strict peer dependencies to ensure performance:
 npm install react-native-lumen react-native-reanimated react-native-svg react-native-gesture-handler react-native-worklets
 ```
 
-## Usage
-
-> **Note**: For a complete, running example showcasing different configurations and styles, check out the `example` folder in this repository.
+```sh
+yarn add react-native-lumen react-native-reanimated react-native-svg react-native-gesture-handler react-native-worklets
+```
 
-1.  **Wrap your App with `TourProvider`**:
+## Quick Start
 
 ```tsx
-import { TourProvider, SnappySpringConfig } from 'react-native-lumen';
+import {
+  TourProvider,
+  TourZone,
+  useTour,
+  SnappySpringConfig,
+} from 'react-native-lumen';
 
+// 1. Wrap your app
 export default function App() {
   return (
     <TourProvider
-      stepsOrder={['bio', 'prompt', 'poll']}
-      config={{
-        springConfig: SnappySpringConfig,
-        enableGlow: true, // Enable the glow effect globally
-        // See config details below
-      }}
+      stepsOrder={['feature-1', 'feature-2']}
+      config={{ springConfig: SnappySpringConfig, enableGlow: true }}
     >
-      <YourComponentThatNeedsTouring />
+      <YourApp />
     </TourProvider>
   );
 }
-```
-
-2.  **Highlight Elements with `TourZone`**:
-
-```tsx
-import { TourZone } from 'react-native-lumen';
 
+// 2. Highlight elements
 <TourZone
-  stepKey="step-1"
+  stepKey="feature-1"
   name="My Feature"
-  description="This is an awesome feature you should know about."
+  description="This is a cool feature."
   order={1}
-  borderRadius={10}
 >
   <MyButton />
 </TourZone>;
-```
-
-3.  **Control the Tour**:
-
-```tsx
-import { useTour } from 'react-native-lumen';
-
-const MyComponent = () => {
-  const { start } = useTour();
-  return <Button title="Start Tour" onPress={() => start()} />;
-};
-```
-
-## API Documentation
-
-### `TourProvider`
-
-The main context provider. Place this at the root of your application.
-
-| Prop              | Type                                   | Default     | Description                                           |
-| :---------------- | :------------------------------------- | :---------- | :---------------------------------------------------- |
-| `children`        | `React.ReactNode`                      | Required    | Application content.                                  |
-| `stepsOrder`      | `string[] \| Record<string, string[]>` | `undefined` | Step ordering. Flat array or screen-grouped object.   |
-| `backdropOpacity` | `number`                               | `0.5`       | Opacity of the dark background overlay (0-1).         |
-| `config`          | `TourConfig`                           | `undefined` | Global configuration options, including `enableGlow`. |
-
-### `TourZone`
-
-Wrapper component to register an element as a tour step. All styling props can also be passed via the `zoneStyle` object prop.
-
-| Prop                 | Type                                   | Default          | Description                                          |
-| :------------------- | :------------------------------------- | :--------------- | :--------------------------------------------------- |
-| `stepKey`            | `string`                               | Required         | Unique identifier for the step.                      |
-| `name`               | `string`                               | `undefined`      | Title of the step.                                   |
-| `description`        | `string`                               | Required         | Description text shown in the tooltip.               |
-| `order`              | `number`                               | `undefined`      | Order of appearance (if `stepsOrder` not used).      |
-| `shape`              | `'rounded-rect' \| 'circle' \| 'pill'` | `'rounded-rect'` | Shape of the zone cutout.                            |
-| `borderRadius`       | `number`                               | `10`             | Border radius of the zone (for rounded-rect).        |
-| `clickable`          | `boolean`                              | `false`          | If `true`, the step remains interactive.             |
-| `preventInteraction` | `boolean`                              | `undefined`      | Overrides global `preventInteraction` for this step. |
-| `required`           | `boolean`                              | `false`          | If `true`, hides the skip button for this step.      |
-| `completed`          | `boolean`                              | `undefined`      | If `false`, disables the next button until `true`.   |
-| `style`              | `ViewStyle`                            | `undefined`      | Style for the wrapping container.                    |
-| `zonePadding`        | `number`                               | `0`              | Uniform padding around the highlighted element.      |
-| `zonePaddingTop`     | `number`                               | `undefined`      | Top padding override.                                |
-| `zonePaddingRight`   | `number`                               | `undefined`      | Right padding override.                              |
-| `zonePaddingBottom`  | `number`                               | `undefined`      | Bottom padding override.                             |
-| `zonePaddingLeft`    | `number`                               | `undefined`      | Left padding override.                               |
-| `zoneBorderWidth`    | `number`                               | `0`              | Width of the zone border.                            |
-| `zoneBorderColor`    | `string`                               | `'transparent'`  | Color of the zone border.                            |
-| `zoneGlowColor`      | `string`                               | `'#FFFFFF'`      | Color of the outer glow effect.                      |
-| `zoneGlowRadius`     | `number`                               | `10`             | Blur radius of the glow effect.                      |
-| `zoneGlowSpread`     | `number`                               | `5`              | Spread radius of the glow effect.                    |
-| `zoneGlowOffsetX`    | `number`                               | `0`              | Horizontal offset of the glow effect.                |
-| `zoneGlowOffsetY`    | `number`                               | `0`              | Vertical offset of the glow effect.                  |
-| `zoneStyle`          | `ZoneStyle`                            | `undefined`      | Complete zone style object (groups above props).     |
-| `renderCustomCard`   | `(props) => ReactNode`                 | `undefined`      | Custom render function for this step's card.         |
-
-### `TourConfig`
-
-Configuration object needed for `TourProvider`.
-
-```tsx
-import { SnappySpringConfig, WigglySpringConfig } from 'react-native-lumen';
 
-interface TourConfig {
-  /**
-   * Animation configuration for the zone movement.
-   * You can use presets like WigglySpringConfig, GentleSpringConfig etc.
-   */
-  springConfig?: WithSpringConfig;
-  /**
-   * If true, prevents interaction with the underlying app while tour is active.
-   */
-  preventInteraction?: boolean;
-  /**
-   * Custom labels for buttons.
-   */
-  labels?: {
-    next?: string;
-    previous?: string;
-    finish?: string;
-    skip?: string;
-  };
-  /**
-   * Custom renderer for the card/tooltip.
-   */
-  renderCard?: (props: CardProps) => React.ReactNode;
-  /**
-   * Initial overlay opacity. Default 0.5
-   */
-  backdropOpacity?: number;
-  /**
-   * Global zone style settings.
-   * Can be overridden per-step via TourZone props.
-   */
-  zoneStyle?: ZoneStyle;
-  /**
-   * Persistence configuration for saving/restoring tour progress.
-   */
-  persistence?: TourPersistenceConfig;
-  /**
-   * Defines whether to apply a shadow/glow effect to the active tour zone highlight.
-   */
-  enableGlow?: boolean;
-  /**
-   * Custom styles for the default tooltip appearance.
-   */
-  tooltipStyles?: TooltipStyles;
-}
-```
-
-### `ZoneStyle`
-
-Customization options for the zone appearance.
-
-```tsx
-interface ZoneStyle {
-  padding?: number; // Uniform padding around the element
-  paddingTop?: number; // Top padding override
-  paddingRight?: number; // Right padding override
-  paddingBottom?: number; // Bottom padding override
-  paddingLeft?: number; // Left padding override
-  borderRadius?: number; // Border radius for 'rounded-rect' shape
-  shape?: 'rounded-rect' | 'circle' | 'pill'; // Zone shape
-  borderWidth?: number; // Border ring width
-  borderColor?: string; // Border color
-  glowColor?: string; // Outer glow color (use rgba/hex-alpha for opacity) (requires enableGlow: true)
-  glowRadius?: number; // Glow blur radius (requires enableGlow: true)
-  glowSpread?: number; // Glow spread radius (requires enableGlow: true)
-  glowOffsetX?: number; // Horizontal offset for the glow (requires enableGlow: true)
-  glowOffsetY?: number; // Vertical offset for the glow (requires enableGlow: true)
-  springDamping?: number; // Per-step spring damping override
-  springStiffness?: number; // Per-step spring stiffness override
-}
-```
-
-### `CardProps`
-
-Props passed to custom card render functions (`renderCard`, `renderCustomCard`).
-
-```tsx
-interface CardProps {
-  step: TourStep;
-  currentStepIndex: number;
-  totalSteps: number;
-  next: () => void;
-  prev: () => void;
-  stop: () => void;
-  isFirst: boolean;
-  isLast: boolean;
-  labels?: TourLabels;
-  required?: boolean; // Whether skip should be hidden
-  completed?: boolean; // Whether next should be disabled (false = disabled)
-}
-```
-
-## Step Enforcement
-
-Use `required` and `completed` props on `TourZone` to control how users progress through the tour.
-
-### `required` - Hide the Skip Button
-
-When `required={true}`, the skip button is hidden. The user must complete the step or press next to continue.
-
-```tsx
-<TourZone
-  stepKey="bio"
-  order={1}
-  description="Edit your bio before continuing."
-  required={true}
->
-  <Bio user={user} />
-</TourZone>
+// 3. Control the tour
+const { start } = useTour();
+<Button title="Start Tour" onPress={() => start()} />;
 ```
 
-### `completed` - Gate the Next Button
+## Documentation
 
-When `completed` is set to `false`, the next/finish button is disabled (grayed out, non-pressable). Once the condition is met and `completed` becomes `true`, the button enables.
+Full API reference, guides, and examples are available on the **[official documentation website](https://thedev204.github.io/react-native-lumen/)**.
 
-```tsx
-const [tourComplete, setTourComplete] = useState(false);
-
-<TourZone
-  stepKey="bio"
-  order={1}
-  description="Double tap to edit your bio and tell others about yourself."
-  required={true}
-  completed={tourComplete}
->
-  <Bio
-    user={User}
-    onUpdateBio={(newBio) => {
-      updateBio(newBio);
-      setTourComplete(true);
-    }}
-  />
-</TourZone>;
-```
-
-### Combining `required` and `completed`
-
-Use both props together for full enforcement:
-
-- `required={true}` - No skip button, user cannot bypass the step.
-- `completed={tourComplete}` - Next button is disabled until `tourComplete` is `true`.
-
-This is useful for onboarding flows where you need the user to perform an action (e.g., edit their bio, upload a photo) before proceeding.
-
-### Enforcement in Custom Cards
-
-When using `renderCard` or `renderCustomCard`, the `required` and `completed` values are passed through `CardProps`. You can use them to control your custom UI:
-
-```tsx
-const MyCustomCard = ({ step, next, stop, required, completed }: CardProps) => (
-  <View style={styles.card}>
-    <Text>{step.description}</Text>
-    <View style={styles.buttons}>
-      {!required && <Button onPress={stop} title="Skip" />}
-      <Button
-        onPress={next}
-        title="Next"
-        disabled={completed === false}
-        color={completed === false ? '#ccc' : '#007AFF'}
-      />
-    </View>
-  </View>
-);
-```
-
-## Multi-Screen Tours
-
-React Native Lumen supports tours that span multiple screens (e.g., tabs in a bottom navigation bar). This is common when your app has separate screens for profile, home, settings, etc.
-
-### The Problem
-
-When using a navigator (e.g., `BottomTabNavigator`, `CurvedBottomBar`), TourZones on inactive screens are not mounted. If the tour tries to advance to a step on an unmounted screen, it would fail because that step hasn't been registered or measured.
-
-### The Solution: Screen-Grouped `stepsOrder`
-
-Pass `stepsOrder` as an object where keys are screen names and values are arrays of step keys:
-
-```tsx
-<TourProvider
-  stepsOrder={{
-    ProfileSelf: ['bio', 'prompt', 'poll'],
-    HomeSwipe: ['filters'],
-    SwipeableCards: ['swipeableCards'],
-  }}
-  config={{
-    springConfig: SnappySpringConfig,
-    preventInteraction: true,
-    persistence: {
-      enabled: true,
-      tourId: 'main-tour',
-      autoResume: true,
-      clearOnComplete: true,
-    },
-  }}
->
-  <CurvedBottomBar.Navigator ...>
-    {/* screens */}
-  </CurvedBottomBar.Navigator>
-</TourProvider>
-```
-
-This is equivalent to a flat array in terms of step ordering:
-
-```tsx
-stepsOrder={['bio', 'prompt', 'poll', 'filters', 'swipeableCards']}
-```
-
-But with the screen-grouped format, the library knows which steps belong to which screen. When the tour advances to a step on a different screen:
-
-1. The overlay hides automatically.
-2. The tour enters a **pending** state, waiting for that step's `TourZone` to mount.
-3. When the user navigates to the correct screen and the `TourZone` mounts, the tour resumes automatically.
-
-### Flat Array (Also Works Cross-Screen)
-
-You can also use a flat array for multi-screen tours. The behavior is the same: if the next step isn't mounted, the tour waits for it:
-
-```tsx
-stepsOrder={['bio', 'prompt', 'poll', 'filters', 'swipeableCards']}
-```
-
-### Example: Multi-Screen Tour
-
-```tsx
-// App.tsx
-<TourProvider
-  stepsOrder={{
-    ProfileSelf: ['bio', 'prompt', 'poll'],
-    HomeSwipe: ['filters'],
-    SwipeableCards: ['swipeableCards'],
-  }}
-  config={{ springConfig: SnappySpringConfig }}
->
-  <BottomTabNavigator />
-</TourProvider>
-
-// ProfileSelf.tsx
-<TourZone stepKey="bio" order={1} description="Edit your bio.">
-  <Bio />
-</TourZone>
-
-<TourZone stepKey="prompt" order={2} description="Add prompts.">
-  <PromptCard />
-</TourZone>
-
-<TourZone stepKey="poll" order={3} description="Create polls.">
-  <PollCard />
-</TourZone>
-
-// HomeSwipe.tsx
-<TourZone stepKey="filters" order={1} description="Filter your matches.">
-  <FilterButton />
-</TourZone>
-
-// SwipeableCards.tsx
-<TourZone stepKey="swipeableCards" order={1} description="Swipe to match!">
-  <CardStack />
-</TourZone>
-```
-
-When the tour finishes the ProfileSelf steps and calls `next()` on the last ProfileSelf step (`poll`), the overlay hides. Once the user navigates to HomeSwipe, the `filters` TourZone mounts and the tour automatically resumes.
-
-## Tour Control (`useTour` Hook)
-
-The `useTour` hook provides full control over the tour lifecycle.
-
-```tsx
-import { useTour } from 'react-native-lumen';
-
-const {
-  start, // Start or resume the tour
-  stop, // Stop the tour (hides overlay, preserves progress)
-  next, // Advance to the next step
-  prev, // Go back to the previous step
-  currentStep, // Currently active step key (null if inactive)
-  steps, // Map of all registered steps
-  orderedStepKeys, // Full ordered list of step keys
-  clearProgress, // Clear saved progress from storage
-  hasSavedProgress, // Whether there's saved progress to resume
-  scrollViewRef, // Attach to your ScrollView for auto-scrolling
-} = useTour();
-```
-
-### `start(stepKey?: string)`
-
-Starts (or resumes) the tour.
-
-- **No arguments**: Starts at the first step. If persistence is enabled with `autoResume: true`, resumes from the last saved step.
-- **With `stepKey`**: Starts at the specified step.
-- If the target step is not mounted yet (on a different screen), the tour enters a pending state and automatically resumes when the step's `TourZone` mounts.
-
-```tsx
-// Start from the beginning (or resume if autoResume is enabled)
-start();
-
-// Start at a specific step
-start('filters');
-```
-
-### `stop()`
-
-Stops the tour and hides the overlay. Does **NOT** clear saved progress. The user can resume later by calling `start()` again.
-
-```tsx
-stop();
-```
+- [Getting Started](https://thedev204.github.io/react-native-lumen/docs/getting-started)
+- [TourProvider](https://thedev204.github.io/react-native-lumen/docs/api/tour-provider)
+- [TourZone](https://thedev204.github.io/react-native-lumen/docs/api/tour-zone)
+- [useTour Hook](https://thedev204.github.io/react-native-lumen/docs/api/use-tour)
+- [Multi-Screen Tours](https://thedev204.github.io/react-native-lumen/docs/guides/multi-screen-tours)
+- [Persistence](https://thedev204.github.io/react-native-lumen/docs/guides/persistence)
 
-### `next()`
+## Changelog
 
-Advances to the next step. If the current step has `completed={false}`, the call is ignored (the user must complete the step first).
+See [CHANGELOG.md](./CHANGELOG.md) for release history.
 
-If the next step is on an unmounted screen, the overlay hides and the tour waits for that step to mount.
+## Contributing
 
-On the last step, `next()` ends the tour and clears progress if `clearOnComplete: true`.
-
-### `prev()`
-
-Goes back to the previous step. If the previous step is on an unmounted screen, the overlay hides and the tour waits for it to mount.
-
-### `clearProgress()`
-
-Manually clears all saved progress from storage. Useful for a "Reset Tour" button.
-
-```tsx
-const { clearProgress } = useTour();
-
-const handleResetTour = async () => {
-  await clearProgress();
-};
-```
-
-## Customization Guide
-
-### Zone Shapes
-
-React Native Lumen supports three zone shapes:
-
-```tsx
-// Rounded rectangle (default)
-<TourZone stepKey="feature" shape="rounded-rect" borderRadius={12}>
-  <MyComponent />
-</TourZone>
-
-// Circle - great for FAB buttons
-<TourZone stepKey="action" shape="circle">
-  <FloatingActionButton />
-</TourZone>
-
-// Pill - great for horizontal elements like tag rows
-<TourZone stepKey="tags" shape="pill">
-  <TagList />
-</TourZone>
-```
-
-### Glow Styles & Per-Step Zone Styling
-
-React Native Lumen features an optional glow effect around the highlighted zone, which can bring a beautiful focus to your UI elements.
-
-**1. Enable Glow Globally**  
-Set `enableGlow: true` in your `TourProvider` config. This allows the glow effect to render.
-
-```tsx
-<TourProvider config={{ enableGlow: true }}>{/* App Content */}</TourProvider>
-```
-
-**2. Customize Per-Step styles**  
-You can customize the standard padding, border, and glow effects per-step using individual `zone*` props or the `zoneStyle` object:
-
-```tsx
-// Using individual props
-<TourZone
-  stepKey="important"
-  zoneGlowColor="rgba(255, 107, 107, 0.6)"
-  zoneBorderColor="#FF6B6B"
-  zoneGlowSpread={5}
-  zoneGlowOffsetY={2}
-  zonePadding={16}
->
-  <ImportantFeature />
-</TourZone>
-
-// Using zoneStyle object
-<TourZone
-  stepKey="premium"
-  zoneStyle={{
-    shape: 'pill',
-    glowColor: 'rgba(255, 215, 0, 0.5)',
-    borderColor: '#FFD700',
-    borderWidth: 3,
-  }}
->
-  <PremiumBadge />
-</TourZone>
-```
-
-### Per-Step Custom Cards
-
-Render custom tooltip cards for specific steps:
-
-```tsx
-<TourZone
-  stepKey="special"
-  renderCustomCard={({ step, next, stop, currentStepIndex, totalSteps }) => (
-    <View style={styles.customCard}>
-      <Text>{step.name}</Text>
-      <Text>{step.description}</Text>
-      <Button title="Continue" onPress={next} />
-    </View>
-  )}
->
-  <SpecialFeature />
-</TourZone>
-```
-
-### Animation Presets
-
-React Native Lumen comes with built-in Reanimated spring configs for easy usage.
-
-```tsx
-import { TourProvider, WigglySpringConfig } from 'react-native-lumen';
-
-<TourProvider config={{ springConfig: WigglySpringConfig }}>...</TourProvider>;
-```
-
-### Auto Scroll Support
-
-React Native Lumen supports auto-scrolling to steps that are off-screen. It perfectly handles long scrollable lists by detecting exactly when the scroll animation finishes before snapping the highlight, ensuring the UI remains smooth.
-
-To enable this, use the `useTourScrollView` hook and spread its props onto your scroll container:
-
-```tsx
-import { useTourScrollView } from 'react-native-lumen';
-import Animated from 'react-native-reanimated';
-
-const MyScrollableScreen = () => {
-  const { scrollViewProps } = useTourScrollView({
-    // Optional: disable user scrolling while the tour is active
-    disableScrollDuringTour: true,
-  });
-
-  return (
-    <Animated.ScrollView {...scrollViewProps}>
-      {/* ... content with TourZones ... */}
-    </Animated.ScrollView>
-  );
-};
-```
-
-> **Note:** The scroll view must be compatible with Reanimated refs (e.g. `Animated.ScrollView`). Spreading `scrollViewProps` automatically wires up the `ref`, `scrollEnabled`, and the `onMomentumScrollEnd` event needed for perfect scroll-end detection and smooth transitions.
-
-Available presets:
-
-- `Reanimated3DefaultSpringConfig`
-- `WigglySpringConfig` (Bouncy)
-- `GentleSpringConfig` (Smooth)
-- `SnappySpringConfig` (Fast & Responsive)
-- `and more!`
-
-### Custom Tooltip Card
-
-You can fully replace the default tooltip with your own beautiful UI using the `renderCard` prop in `config`.
-
-```tsx
-import { TourProvider, CardProps } from 'react-native-lumen';
-
-const CustomCard = ({
-  step,
-  next,
-  prev,
-  stop,
-  isLast,
-  currentStepIndex,
-  totalSteps,
-  required,
-  completed,
-}: CardProps) => (
-  <View style={{ padding: 20, backgroundColor: 'white', borderRadius: 20 }}>
-    <Text style={{ fontWeight: 'bold', fontSize: 20 }}>{step.name}</Text>
-    <Text>{step.description}</Text>
-    <Text style={{ color: 'gray' }}>
-      Step {currentStepIndex + 1} of {totalSteps}
-    </Text>
-
-    <View style={{ flexDirection: 'row', marginTop: 10 }}>
-      {!required && <Button onPress={stop} title="Close" />}
-      <View style={{ flex: 1 }} />
-      {!isLast ? (
-        <Button onPress={next} title="Next" disabled={completed === false} />
-      ) : (
-        <Button onPress={next} title="Finish" disabled={completed === false} />
-      )}
-    </View>
-  </View>
-);
-
-export default function App() {
-  return (
-    <TourProvider config={{ renderCard: (props) => <CustomCard {...props} /> }}>
-      <AppContent />
-    </TourProvider>
-  );
-}
-```
-
-### Persistence (Resume Tours)
-
-React Native Lumen supports saving tour progress so users can resume where they left off. The library auto-detects available storage (MMKV v4 or AsyncStorage).
-
-```tsx
-import { TourProvider } from 'react-native-lumen';
-
-export default function App() {
-  return (
-    <TourProvider
-      config={{
-        persistence: {
-          enabled: true,
-          tourId: 'onboarding-v1', // Unique ID for this tour
-          autoResume: true, // Auto-resume from saved step (default: true)
-          clearOnComplete: true, // Clear progress when tour finishes (default: true)
-          maxAge: 7 * 24 * 60 * 60 * 1000, // Optional: expire after 7 days
-        },
-      }}
-    >
-      <AppContent />
-    </TourProvider>
-  );
-}
-```
-
-#### Storage Support
-
-The library automatically detects and uses:
-
-- **MMKV v4** (`react-native-mmkv` ^4.0.0) - Fastest, recommended
-- **AsyncStorage** (`@react-native-async-storage/async-storage`) - Fallback
-
-No additional setup required if either package is installed.
-
-#### Custom Storage
-
-You can provide a custom storage adapter:
-
-```tsx
-import { TourProvider, type StorageAdapter } from 'react-native-lumen';
-
-const customStorage: StorageAdapter = {
-  getItem: (key) => myStorage.get(key),
-  setItem: (key, value) => myStorage.set(key, value),
-  removeItem: (key) => myStorage.remove(key),
-};
-
-<TourProvider
-  config={{
-    persistence: {
-      enabled: true,
-      tourId: 'my-tour',
-      storage: customStorage,
-    },
-  }}
->
-  ...
-</TourProvider>;
-```
-
-#### Persistence API
-
-```tsx
-const { start, clearProgress, hasSavedProgress } = useTour();
-
-// Check if there's saved progress
-if (hasSavedProgress) {
-  // Show "Resume Tour" button
-}
-
-// Start tour (auto-resumes if enabled)
-start();
-
-// Clear saved progress manually
-await clearProgress();
-```
-
-#### Manually Clearing Storage
-
-If you need to clear tour data directly from storage outside the tour context (e.g., during logout or a full app reset):
-
-**MMKV v4:**
-
-```tsx
-import { createMMKV } from 'react-native-mmkv';
-
-// The library uses a dedicated MMKV instance with this ID
-const storage = createMMKV({ id: 'react-native-lumen-tour' });
-
-// Clear a specific tour
-storage.remove('@lumen_tour_onboarding-v1');
-
-// Or clear all tour data - delete all keys starting with @lumen_tour_
-const allKeys = storage.getAllKeys();
-allKeys
-  .filter((key) => key.startsWith('@lumen_tour_'))
-  .forEach((key) => storage.remove(key));
-```
-
-**AsyncStorage:**
-
-```tsx
-import AsyncStorage from '@react-native-async-storage/async-storage';
-
-// Clear a specific tour
-await AsyncStorage.removeItem('@lumen_tour_onboarding-v1');
-
-// Or clear all tour data
-const allKeys = await AsyncStorage.getAllKeys();
-const tourKeys = allKeys.filter((key) => key.startsWith('@lumen_tour_'));
-await AsyncStorage.multiRemove(tourKeys);
-```
+Contributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) before submitting a pull request.
 
-The storage key format is `@lumen_tour_{tourId}` where `tourId` is the value you passed in `persistence.tourId`.
+- Report bugs in the [Issue Tracker](https://github.com/thedev204/react-native-lumen/issues).
 
 ## License
 
-MIT
+MIT

package/lib/module/components/TourOverlay.js

@@ -10,7 +10,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const {
   width: SCREEN_WIDTH,
   height: SCREEN_HEIGHT
-} = Dimensions.get('window');
+} = Dimensions.get('screen');
 const AnimatedPath = Animated.createAnimatedComponent(Path);
 const AnimatedView = Animated.View;
 

package/lib/module/components/TourProvider.js

@@ -12,11 +12,11 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const {
   width: SCREEN_WIDTH,
   height: SCREEN_HEIGHT
-} = Dimensions.get('window');
+} = Dimensions.get('screen');
 
-/**
- * Computes the zone geometry based on element bounds and zone style.
- * Handles different shapes: rounded-rect, circle, pill.
+/**
+ * Computes the zone geometry based on element bounds and zone style.
+ * Handles different shapes: rounded-rect, circle, pill.
  */
 function computeZoneGeometry(element, style) {
   const {
@@ -111,9 +111,9 @@ export const TourProvider = ({
     onScrollEndCallbackRef.current = null;
   }, []);
 
-  /**
-   * One-shot: fires the registered callback and immediately clears it so that
-   * user-initiated momentum scrolls that happen between steps don't re-trigger.
+  /**
+   * One-shot: fires the registered callback and immediately clears it so that
+   * user-initiated momentum scrolls that happen between steps don't re-trigger.
    */
   const triggerScrollEnd = useCallback(() => {
     const cb = onScrollEndCallbackRef.current;

package/lib/module/components/TourTooltip.js

@@ -9,7 +9,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const {
   width: SCREEN_WIDTH,
   height: SCREEN_HEIGHT
-} = Dimensions.get('window');
+} = Dimensions.get('screen');
 const getDynamicStyles = tooltipStyles => {
   const defaultStyles = {
     backgroundColor: tooltipStyles?.backgroundColor || 'white',

package/lib/module/components/TourZone.js

@@ -7,7 +7,7 @@ import { Dimensions } from 'react-native';
 import { jsx as _jsx } from "react/jsx-runtime";
 const {
   height: SCREEN_HEIGHT
-} = Dimensions.get('window');
+} = Dimensions.get('screen');
 const AnimatedView = Animated.View;
 export const TourZone = ({
   stepKey,

package/lib/module/constants/animations.js

@@ -1,7 +1,7 @@
 "use strict";
 
-/**
- * Default spring configuration matching Reanimated 3 defaults.
+/**
+ * Default spring configuration matching Reanimated 3 defaults.
  */
 export const Reanimated3DefaultSpringConfig = {
   damping: 10,
@@ -9,16 +9,16 @@ export const Reanimated3DefaultSpringConfig = {
   stiffness: 100
 };
 
-/**
- * Spring configuration with duration.
+/**
+ * Spring configuration with duration.
  */
 export const Reanimated3DefaultSpringConfigWithDuration = {
   duration: 1333,
   dampingRatio: 0.5
 };
 
-/**
- * A bouncy and energetic spring configuration.
+/**
+ * A bouncy and energetic spring configuration.
  */
 export const WigglySpringConfig = {
   damping: 90,
@@ -26,16 +26,16 @@ export const WigglySpringConfig = {
   stiffness: 900
 };
 
-/**
- * A bouncy spring configuration with fixed duration.
+/**
+ * A bouncy spring configuration with fixed duration.
  */
 export const WigglySpringConfigWithDuration = {
   duration: 550,
   dampingRatio: 0.75
 };
 
-/**
- * A gentle and smooth spring configuration.
+/**
+ * A gentle and smooth spring configuration.
  */
 export const GentleSpringConfig = {
   damping: 120,
@@ -43,16 +43,16 @@ export const GentleSpringConfig = {
   stiffness: 900
 };
 
-/**
- * A gentle spring configuration with fixed duration.
+/**
+ * A gentle spring configuration with fixed duration.
  */
 export const GentleSpringConfigWithDuration = {
   duration: 550,
   dampingRatio: 1
 };
 
-/**
- * A snappy and responsive spring configuration.
+/**
+ * A snappy and responsive spring configuration.
  */
 export const SnappySpringConfig = {
   damping: 110,
@@ -61,8 +61,8 @@ export const SnappySpringConfig = {
   overshootClamping: true
 };
 
-/**
- * A snappy spring configuration with fixed duration.
+/**
+ * A snappy spring configuration with fixed duration.
  */
 export const SnappySpringConfigWithDuration = {
   duration: 550,

package/lib/module/constants/defaults.js

@@ -12,9 +12,9 @@ export const DEFAULT_LABELS = {
   skip: 'Skip'
 };
 
-/**
- * Default zone style configuration.
- * These values are used when no custom style is provided.
+/**
+ * Default zone style configuration.
+ * These values are used when no custom style is provided.
  */
 export const DEFAULT_ZONE_STYLE = {
   padding: 0,
@@ -35,8 +35,8 @@ export const DEFAULT_ZONE_STYLE = {
   springStiffness: 90
 };
 
-/**
- * Merges global and per-step zone styles with defaults.
+/**
+ * Merges global and per-step zone styles with defaults.
  */
 export function resolveZoneStyle(globalStyle, stepStyle) {
   const merged = {

package/lib/module/hooks/useTourScrollView.js

@@ -2,28 +2,28 @@
 
 import { useCallback, useMemo } from 'react';
 import { useTour } from "./useTour.js";
-/**
- * Hook to simplify integrating custom scroll views with the tour system.
- *
- * @example
- * // Basic usage with Animated.ScrollView
- * const { scrollViewRef } = useTourScrollView();
- * return <Animated.ScrollView ref={scrollViewRef}>...</Animated.ScrollView>;
- *
- * @example
- * // With scroll disabled during tour
- * const { scrollViewProps } = useTourScrollView({ disableScrollDuringTour: true });
- * return <Animated.ScrollView {...scrollViewProps}>...</Animated.ScrollView>;
- *
- * @example
- * // Custom scroll view wrapper (forwardRef pattern)
- * const MyScrollView = forwardRef((props, ref) => {
- *   const { scrollViewRef } = useTourScrollView();
- *   useImperativeHandle(ref, () => ({
- *     getScrollRef: () => scrollViewRef.current,
- *   }));
- *   return <Animated.ScrollView ref={scrollViewRef} {...props} />;
- * });
+/**
+ * Hook to simplify integrating custom scroll views with the tour system.
+ *
+ * @example
+ * // Basic usage with Animated.ScrollView
+ * const { scrollViewRef } = useTourScrollView();
+ * return <Animated.ScrollView ref={scrollViewRef}>...</Animated.ScrollView>;
+ *
+ * @example
+ * // With scroll disabled during tour
+ * const { scrollViewProps } = useTourScrollView({ disableScrollDuringTour: true });
+ * return <Animated.ScrollView {...scrollViewProps}>...</Animated.ScrollView>;
+ *
+ * @example
+ * // Custom scroll view wrapper (forwardRef pattern)
+ * const MyScrollView = forwardRef((props, ref) => {
+ *   const { scrollViewRef } = useTourScrollView();
+ *   useImperativeHandle(ref, () => ({
+ *     getScrollRef: () => scrollViewRef.current,
+ *   }));
+ *   return <Animated.ScrollView ref={scrollViewRef} {...props} />;
+ * });
  */
 export function useTourScrollView(options = {}) {
   const {

package/lib/module/utils/storage.js

@@ -1,8 +1,8 @@
 "use strict";
 
-/**
- * Storage adapter for tour persistence.
- * Auto-detects available storage (MMKV v4 or AsyncStorage) and provides a unified interface.
+/**
+ * Storage adapter for tour persistence.
+ * Auto-detects available storage (MMKV v4 or AsyncStorage) and provides a unified interface.
  */
 
 // ─── Types ───────────────────────────────────────────────────────────────────
@@ -12,9 +12,9 @@
 let cachedStorageType = null;
 let cachedAdapter = null;
 
-/**
- * Attempts to detect and return the MMKV v4 default instance.
- * Returns null if MMKV is not available.
+/**
+ * Attempts to detect and return the MMKV v4 default instance.
+ * Returns null if MMKV is not available.
  */
 function tryGetMMKV() {
   try {
@@ -43,9 +43,9 @@ function tryGetMMKV() {
   }
 }
 
-/**
- * Attempts to detect and return AsyncStorage.
- * Returns null if AsyncStorage is not available.
+/**
+ * Attempts to detect and return AsyncStorage.
+ * Returns null if AsyncStorage is not available.
  */
 function tryGetAsyncStorage() {
   try {
@@ -66,9 +66,9 @@ function tryGetAsyncStorage() {
   }
 }
 
-/**
- * Detects the available storage type and returns an adapter.
- * Priority: MMKV v4 > AsyncStorage > none
+/**
+ * Detects the available storage type and returns an adapter.
+ * Priority: MMKV v4 > AsyncStorage > none
  */
 export function detectStorage() {
   // Return cached result if available
@@ -110,9 +110,9 @@ export function detectStorage() {
   };
 }
 
-/**
- * Clears the cached storage detection result.
- * Useful for testing or when storage availability changes.
+/**
+ * Clears the cached storage detection result.
+ * Useful for testing or when storage availability changes.
  */
 export function clearStorageCache() {
   cachedStorageType = null;
@@ -123,8 +123,8 @@ export function clearStorageCache() {
 
 const STORAGE_KEY_PREFIX = '@lumen_tour_';
 
-/**
- * Generates a storage key for a specific tour.
+/**
+ * Generates a storage key for a specific tour.
  */
 export function getTourStorageKey(tourId) {
   return `${STORAGE_KEY_PREFIX}${tourId}`;
@@ -132,8 +132,8 @@ export function getTourStorageKey(tourId) {
 
 // ─── Storage Operations ──────────────────────────────────────────────────────
 
-/**
- * Saves the current tour progress to storage.
+/**
+ * Saves the current tour progress to storage.
  */
 export async function saveTourProgress(adapter, tourId, currentStepKey, stepIndex) {
   const state = {
@@ -147,9 +147,9 @@ export async function saveTourProgress(adapter, tourId, currentStepKey, stepInde
   await adapter.setItem(key, value);
 }
 
-/**
- * Loads the saved tour progress from storage.
- * Returns null if no progress is saved or if the data is invalid.
+/**
+ * Loads the saved tour progress from storage.
+ * Returns null if no progress is saved or if the data is invalid.
  */
 export async function loadTourProgress(adapter, tourId) {
   try {
@@ -170,16 +170,16 @@ export async function loadTourProgress(adapter, tourId) {
   }
 }
 
-/**
- * Clears the saved tour progress from storage.
+/**
+ * Clears the saved tour progress from storage.
  */
 export async function clearTourProgress(adapter, tourId) {
   const key = getTourStorageKey(tourId);
   await adapter.removeItem(key);
 }
 
-/**
- * Checks if there is saved progress for a tour.
+/**
+ * Checks if there is saved progress for a tour.
  */
 export async function hasTourProgress(adapter, tourId) {
   const progress = await loadTourProgress(adapter, tourId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-lumen",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "A customizable app tour library for React Native",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -50,7 +50,7 @@
   "bugs": {
     "url": "https://github.com/thedev204/react-native-lumen/issues"
   },
-  "homepage": "https://github.com/thedev204/react-native-lumen#readme",
+  "homepage": "https://thedev204.github.io/react-native-lumen/",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },