onstage 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Asad Ullah Khalid
+
+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

@@ -0,0 +1,230 @@
+# 🎭 Onstage
+
+**The premium, plug-and-play onboarding wizard for React.**
+
+Turn your new user experience into a polished, professional tour in minutes. `onstage` provides a beautiful, responsive, and fully customizable modal wizard with zero friction.
+
+![Onstage Demo](https://placehold.co/800x400/1e293b/fff?text=Onstage+Library+Preview)
+
+## ✨ Features
+
+- **🎨 7 Pre-built Themes:** From "Glassmorphism" to "Midnight" dark mode.
+- **📱 Fully Responsive:** Adapts visuals for Mobile, Tablet, and Desktop automatically.
+- **🔌 Plug & Play:** Just pass an array of steps and it renders.
+- **🌫️ Backdrop Control:** Choose between dark, blurred, or transparent overlays.
+- **🎮 Flexible Control:** Strict mode (force completion) or Permissive (click outside to close).
+- **💅 Granular Styling:** Override any part of the UI with Tailwind classes or CSS variables.
+
+## 📦 Installation
+
+```bash
+npm install onstage
+# or
+pnpm add onstage
+# or
+yarn add onstage
+```
+
+## 🚀 Quick Start
+
+### 1. Import Styles
+Add this **once** to your root file (e.g., `main.tsx` or `App.tsx`):
+
+```tsx
+import "onstage/styles.css";
+```
+
+### 2. Wrap & Use
+Wrap your app (or just the section you need) with the Provider and place the Modal.
+
+```tsx
+import { OnboardingProvider, OnboardingModal } from "onstage";
+
+const steps = [
+  {
+    title: "Welcome! 👋",
+    description: "We are **thrilled** to have you here.",
+    image: "/images/welcome-desktop.png"
+  },
+  {
+    title: "Features",
+    description: "Explore our new dashboard.",
+    image: "/images/dashboard.png"
+  }
+];
+
+export default function App() {
+  return (
+    <OnboardingProvider steps={steps} defaultOpen={true}>
+      <YourApp />
+      <OnboardingModal />
+    </OnboardingProvider>
+  );
+}
+```
+
+---
+
+## 🎨 Themes & Aesthetics
+
+`onstage` comes with professional presets so you don't have to design from scratch.
+
+### Preset Themes
+Pass the `theme` prop to switch styles instantly.
+
+```tsx
+// 🌑 Professional Dark Mode
+<OnboardingModal theme="dark" />
+
+// 🪟 Frosted Glass Effect
+<OnboardingModal theme="glass" />
+
+// 🌌 Deep Purple "Midnight"
+<OnboardingModal theme="midnight" />
+
+// 📐 Minimalist (Brutalist / Sharp)
+<OnboardingModal theme="minimal" />
+```
+
+**Available Themes:**
+- `light` (Default)
+- `dark`
+- `glass`
+- `midnight`
+- `minimal`
+- `ocean`
+- `sunset`
+
+### Backdrop Effects
+Control the overlay behind the modal.
+
+```tsx
+// 🌫️ Frosted background
+<OnboardingModal backdrop="blur" />
+
+// 👻 Invisible overlay (content visible but not clickable)
+<OnboardingModal backdrop="transparent" />
+```
+
+---
+
+## 📱 Responsive Images
+
+Don't serve a desktop screenshot on a mobile phone. `onstage` lets you define specific images for different devices. It automatically adjusts the aspect ratio (`4:5` mobile, `4:3` tablet, `16:9` desktop) to fit the modal perfectly.
+
+```tsx
+const steps = [
+  {
+    title: "Responsive Magic",
+    description: "Resize your browser to see the image change!",
+    image: {
+      mobile: "/img/hero-portrait.png",  // < 640px (4:5 Ratio)
+      tablet: "/img/hero-square.png",    // < 1024px (4:3 Ratio)
+      desktop: "/img/hero-landscape.png" // > 1024px (16:9 Ratio)
+    }
+  }
+];
+```
+
+---
+
+## 🎮 Interaction & Control
+
+### Strict vs. Permissive Mode
+Decide if users *must* complete the onboarding or if they can dismiss it easily.
+
+```tsx
+// 🔓 Permissive Mode (Default)
+// Users can click the background or press ESC to dismiss.
+<OnboardingModal allowClickOutside={true} />
+
+// 🔒 Strict Mode
+// Users MUST finish the steps or click "Skip". Background click is disabled.
+<OnboardingModal allowClickOutside={false} />
+```
+
+### Programmatic Control
+Control the wizard from anywhere in your app using the hook.
+
+```tsx
+import { useOnboarding } from "onstage";
+
+function SettingsPage() {
+  const { resetOnboarding } = useOnboarding();
+
+  return (
+    <button onClick={resetOnboarding}>
+      Show Tutorial Again
+    </button>
+  );
+}
+```
+
+**Available Hook Methods:**
+- `resetOnboarding()`: Opens modal at step 0.
+- `setIsOpen(boolean)`: Manually toggle visibility.
+- `skipOnboarding()`: Closes modal and triggers `onSkip`.
+- `finishOnboarding()`: Closes modal and triggers `onFinish`.
+
+---
+
+## 🛠️ Advanced Customization
+
+### CSS Variables
+Tweak the branding colors globally or inline.
+
+```tsx
+<OnboardingModal
+  style={{
+    '--primary': '262 80% 50%', // Custom Purple
+    '--radius': '1rem'          // Rounder corners
+  } as React.CSSProperties}
+/>
+```
+
+### Granular Targeting
+Need to style *just* the "Next" button? Use `classNames` (supports Tailwind) or `styles` to target specific elements.
+
+```tsx
+<OnboardingModal
+  classNames={{
+    // Add red background to next button
+    nextButton: "bg-red-500 hover:bg-red-600 font-bold",
+    // Make title blue
+    title: "text-blue-600 underline",
+    // Custom overlay
+    overlay: "bg-slate-900/90"
+  }}
+/>
+```
+
+**Targetable Elements:** `overlay`, `content`, `imageContainer`, `image`, `header`, `title`, `description`, `footer`, `stepIndicators`, `nextButton`, `prevButton`, `skipButton`, `finishButton`.
+
+---
+
+## 📚 API Reference
+
+### `OnboardingModal` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `theme` | `string` | `"light"` | `light`, `dark`, `glass`, `minimal`, `midnight`, `ocean`, `sunset` |
+| `backdrop` | `string` | `"default"` | `default` (dark), `blur`, `transparent` |
+| `allowClickOutside` | `boolean` | `true` | If true, clicking overlay closes the modal. |
+| `gradient` | `string` | `"animated"` | `animated`, `static`, `none` |
+| `className` | `string` | `-` | Class for the main modal container. |
+| `classNames` | `object` | `{}` | Target specific elements (see above). |
+| `style` | `CSSProperties` | `{}` | Inline styles for the root. |
+
+### `OnboardingProvider` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `steps` | `OnboardingStep[]` | **Required** | Array of step data. |
+| `defaultOpen` | `boolean` | `false` | If true, opens immediately on mount. |
+| `onFinish` | `() => void` | `-` | Callback when user finishes all steps. |
+| `onSkip` | `() => void` | `-` | Callback when user clicks "Skip". |
+
+## License
+
+MIT © Asad Ullah Khalid

package/dist/index.d.mts

@@ -0,0 +1,108 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, CSSProperties } from 'react';
+
+interface OnboardingStep {
+    title: string;
+    description: string;
+    image: string | {
+        mobile: string;
+        tablet?: string;
+        desktop: string;
+    };
+}
+interface OnboardingContextValue {
+    isOpen: boolean;
+    currentStepIndex: number;
+    steps: OnboardingStep[];
+    nextStep: () => void;
+    prevStep: () => void;
+    skipOnboarding: () => void;
+    finishOnboarding: () => void;
+    resetOnboarding: () => void;
+    setIsOpen: (isOpen: boolean) => void;
+}
+interface OnboardingProviderProps {
+    children: ReactNode;
+    steps: OnboardingStep[];
+    defaultOpen?: boolean;
+    onFinish?: () => void;
+    onSkip?: () => void;
+}
+declare function OnboardingProvider({ children, steps, defaultOpen, onFinish, onSkip, }: OnboardingProviderProps): react_jsx_runtime.JSX.Element;
+declare function useOnboarding(): OnboardingContextValue;
+
+type OnboardingTheme = "light" | "dark" | "minimal" | "glass" | "midnight" | "ocean" | "sunset";
+interface OnboardingModalProps {
+    /**
+     * The aesthetic theme of the modal.
+     */
+    theme?: OnboardingTheme;
+    /**
+     * Controls the background gradient style.
+     */
+    gradient?: "animated" | "static" | "none";
+    /**
+     * Controls the visual style of the backdrop overlay.
+     * - `default`: Standard dark dimming.
+     * - `blur`: Clean frosted glass effect (blur only).
+     * - `transparent`: Invisible overlay.
+     * @default "default"
+     */
+    backdrop?: "default" | "blur" | "transparent";
+    /**
+     * Pass a custom Tailwind class for the gradient background.
+     */
+    customGradientClass?: string;
+    /**
+     * Inline styles to apply to the modal content.
+     */
+    style?: CSSProperties;
+    /**
+     * Additional class names for the modal container.
+     */
+    className?: string;
+    /**
+     * Whether to allow closing the modal by clicking the overlay or pressing Escape.
+     * @default true
+     */
+    allowClickOutside?: boolean;
+    /**
+     * Target specific internal elements for styling.
+     */
+    classNames?: {
+        overlay?: string;
+        content?: string;
+        imageContainer?: string;
+        image?: string;
+        header?: string;
+        title?: string;
+        description?: string;
+        footer?: string;
+        stepIndicators?: string;
+        nextButton?: string;
+        prevButton?: string;
+        skipButton?: string;
+        finishButton?: string;
+    };
+    /**
+     * Target specific internal elements with inline styles.
+     */
+    styles?: {
+        overlay?: CSSProperties;
+        content?: CSSProperties;
+        imageContainer?: CSSProperties;
+        image?: CSSProperties;
+        header?: CSSProperties;
+        title?: CSSProperties;
+        description?: CSSProperties;
+        footer?: CSSProperties;
+        stepIndicators?: CSSProperties;
+        nextButton?: CSSProperties;
+        prevButton?: CSSProperties;
+        skipButton?: CSSProperties;
+        finishButton?: CSSProperties;
+    };
+}
+declare function OnboardingModal({ theme, gradient, backdrop, customGradientClass, style, className, allowClickOutside, classNames, styles, }: OnboardingModalProps): react_jsx_runtime.JSX.Element | null;
+
+export { OnboardingModal, type OnboardingModalProps, OnboardingProvider, type OnboardingStep, type OnboardingTheme, useOnboarding };

package/dist/index.d.ts

@@ -0,0 +1,108 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, CSSProperties } from 'react';
+
+interface OnboardingStep {
+    title: string;
+    description: string;
+    image: string | {
+        mobile: string;
+        tablet?: string;
+        desktop: string;
+    };
+}
+interface OnboardingContextValue {
+    isOpen: boolean;
+    currentStepIndex: number;
+    steps: OnboardingStep[];
+    nextStep: () => void;
+    prevStep: () => void;
+    skipOnboarding: () => void;
+    finishOnboarding: () => void;
+    resetOnboarding: () => void;
+    setIsOpen: (isOpen: boolean) => void;
+}
+interface OnboardingProviderProps {
+    children: ReactNode;
+    steps: OnboardingStep[];
+    defaultOpen?: boolean;
+    onFinish?: () => void;
+    onSkip?: () => void;
+}
+declare function OnboardingProvider({ children, steps, defaultOpen, onFinish, onSkip, }: OnboardingProviderProps): react_jsx_runtime.JSX.Element;
+declare function useOnboarding(): OnboardingContextValue;
+
+type OnboardingTheme = "light" | "dark" | "minimal" | "glass" | "midnight" | "ocean" | "sunset";
+interface OnboardingModalProps {
+    /**
+     * The aesthetic theme of the modal.
+     */
+    theme?: OnboardingTheme;
+    /**
+     * Controls the background gradient style.
+     */
+    gradient?: "animated" | "static" | "none";
+    /**
+     * Controls the visual style of the backdrop overlay.
+     * - `default`: Standard dark dimming.
+     * - `blur`: Clean frosted glass effect (blur only).
+     * - `transparent`: Invisible overlay.
+     * @default "default"
+     */
+    backdrop?: "default" | "blur" | "transparent";
+    /**
+     * Pass a custom Tailwind class for the gradient background.
+     */
+    customGradientClass?: string;
+    /**
+     * Inline styles to apply to the modal content.
+     */
+    style?: CSSProperties;
+    /**
+     * Additional class names for the modal container.
+     */
+    className?: string;
+    /**
+     * Whether to allow closing the modal by clicking the overlay or pressing Escape.
+     * @default true
+     */
+    allowClickOutside?: boolean;
+    /**
+     * Target specific internal elements for styling.
+     */
+    classNames?: {
+        overlay?: string;
+        content?: string;
+        imageContainer?: string;
+        image?: string;
+        header?: string;
+        title?: string;
+        description?: string;
+        footer?: string;
+        stepIndicators?: string;
+        nextButton?: string;
+        prevButton?: string;
+        skipButton?: string;
+        finishButton?: string;
+    };
+    /**
+     * Target specific internal elements with inline styles.
+     */
+    styles?: {
+        overlay?: CSSProperties;
+        content?: CSSProperties;
+        imageContainer?: CSSProperties;
+        image?: CSSProperties;
+        header?: CSSProperties;
+        title?: CSSProperties;
+        description?: CSSProperties;
+        footer?: CSSProperties;
+        stepIndicators?: CSSProperties;
+        nextButton?: CSSProperties;
+        prevButton?: CSSProperties;
+        skipButton?: CSSProperties;
+        finishButton?: CSSProperties;
+    };
+}
+declare function OnboardingModal({ theme, gradient, backdrop, customGradientClass, style, className, allowClickOutside, classNames, styles, }: OnboardingModalProps): react_jsx_runtime.JSX.Element | null;
+
+export { OnboardingModal, type OnboardingModalProps, OnboardingProvider, type OnboardingStep, type OnboardingTheme, useOnboarding };