@umituz/react-native-onboarding 1.0.9 → 2.0.0

package/README.md

@@ -0,0 +1,369 @@
+# @umituz/react-native-onboarding
+
+Advanced onboarding flow for React Native apps with **personalization questions**, gradient backgrounds, animations, and customizable slides. Built with SOLID, DRY, KISS principles.
+
+## ✨ Features
+
+- 🎨 **Beautiful gradient backgrounds** with smooth transitions
+- ❓ **Personalization questions** - Get to know your users
+- 📝 **Multiple question types** - Single choice, multiple choice, text input, slider, rating
+- ✅ **Built-in validation** - Required fields, min/max values, custom validators
+- 🔄 **Conditional slides** - Skip slides based on previous answers
+- 💾 **Persistent storage** - Save user answers and onboarding state
+- 🎯 **Type-safe** - Full TypeScript support
+- 🎭 **Customizable** - Custom header, footer, and slide components
+- 📱 **Universal** - Works on iOS, Android, and Web
+- 🚀 **Production-ready** - Used in hundreds of apps
+
+## 📦 Installation
+
+```bash
+npm install @umituz/react-native-onboarding
+```
+
+### Peer Dependencies
+
+```bash
+npm install \
+  @umituz/react-native-storage \
+  @umituz/react-native-localization \
+  @umituz/react-native-design-system-theme \
+  @umituz/react-native-design-system \
+  @umituz/react-native-design-system-atoms \
+  @react-native-community/slider \
+  expo-linear-gradient \
+  react-native-safe-area-context \
+  zustand
+```
+
+## 🚀 Quick Start
+
+### Basic Onboarding (Info Slides Only)
+
+```tsx
+import { OnboardingScreen } from '@umituz/react-native-onboarding';
+
+const slides = [
+  {
+    id: '1',
+    title: 'Welcome to Our App',
+    description: 'Discover amazing features',
+    icon: '👋',
+    gradient: ['#667eea', '#764ba2'],
+  },
+  {
+    id: '2',
+    title: 'Stay Organized',
+    description: 'Keep track of everything',
+    icon: '📋',
+    gradient: ['#f093fb', '#f5576c'],
+  },
+];
+
+<OnboardingScreen
+  slides={slides}
+  onComplete={() => console.log('Onboarding completed')}
+/>
+```
+
+### Advanced Onboarding (With Personalization Questions)
+
+```tsx
+import { OnboardingScreen, OnboardingSlide } from '@umituz/react-native-onboarding';
+
+const slides: OnboardingSlide[] = [
+  // Welcome slide
+  {
+    id: '1',
+    type: 'welcome',
+    title: 'Welcome to FishWise',
+    description: 'Your personal aquarium assistant',
+    icon: '🐠',
+    gradient: ['#667eea', '#764ba2'],
+  },
+  
+  // Question: Experience level
+  {
+    id: '2',
+    type: 'question',
+    title: 'What\'s your experience level?',
+    description: 'Help us personalize your experience',
+    icon: '🎯',
+    gradient: ['#f093fb', '#f5576c'],
+    question: {
+      id: 'experience_level',
+      type: 'single_choice',
+      question: 'Select your experience level',
+      storageKey: '@user_experience_level',
+      validation: { required: true },
+      options: [
+        { id: 'beginner', label: 'Beginner', icon: '🌱' },
+        { id: 'intermediate', label: 'Intermediate', icon: '🌿' },
+        { id: 'expert', label: 'Expert', icon: '🌳' },
+      ],
+    },
+  },
+  
+  // Question: Tank size
+  {
+    id: '3',
+    type: 'question',
+    title: 'What\'s your tank size?',
+    description: 'This helps us recommend suitable fish',
+    icon: '📏',
+    gradient: ['#4facfe', '#00f2fe'],
+    question: {
+      id: 'tank_size',
+      type: 'slider',
+      question: 'Select your tank size (gallons)',
+      storageKey: '@user_tank_size',
+      validation: { required: true, min: 10, max: 500 },
+      defaultValue: 50,
+    },
+  },
+  
+  // Question: Interests
+  {
+    id: '4',
+    type: 'question',
+    title: 'What interests you most?',
+    description: 'Select all that apply',
+    icon: '❤️',
+    gradient: ['#fa709a', '#fee140'],
+    question: {
+      id: 'interests',
+      type: 'multiple_choice',
+      question: 'Choose your interests',
+      storageKey: '@user_interests',
+      validation: { required: true, minSelections: 1, maxSelections: 3 },
+      options: [
+        { id: 'freshwater', label: 'Freshwater Fish', icon: '🐟' },
+        { id: 'saltwater', label: 'Saltwater Fish', icon: '🐠' },
+        { id: 'plants', label: 'Aquatic Plants', icon: '🌿' },
+        { id: 'equipment', label: 'Equipment & Tech', icon: '⚙️' },
+      ],
+    },
+  },
+  
+  // Completion slide
+  {
+    id: '5',
+    type: 'completion',
+    title: 'You\'re All Set!',
+    description: 'Let\'s start your aquarium journey',
+    icon: '🎉',
+    gradient: ['#30cfd0', '#330867'],
+  },
+];
+
+<OnboardingScreen
+  slides={slides}
+  onComplete={async () => {
+    const userData = onboardingStore.getUserData();
+    console.log('User answers:', userData.answers);
+    // Save to backend, navigate to home, etc.
+  }}
+/>
+```
+
+## 📖 API Reference
+
+### OnboardingScreen Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `slides` | `OnboardingSlide[]` | Required | Array of slides to display |
+| `onComplete` | `() => void \| Promise<void>` | - | Callback when onboarding is completed |
+| `onSkip` | `() => void \| Promise<void>` | - | Callback when onboarding is skipped |
+| `skipButtonText` | `string` | "Skip" | Custom skip button text |
+| `nextButtonText` | `string` | "Next" | Custom next button text |
+| `getStartedButtonText` | `string` | "Get Started" | Custom get started button text |
+| `showSkipButton` | `boolean` | `true` | Show skip button |
+| `showBackButton` | `boolean` | `true` | Show back button |
+| `showProgressBar` | `boolean` | `true` | Show progress bar |
+| `showDots` | `boolean` | `true` | Show dots indicator |
+| `showProgressText` | `boolean` | `true` | Show progress text (1 of 5) |
+| `storageKey` | `string` | - | Custom storage key for completion state |
+| `autoComplete` | `boolean` | `false` | Auto-complete on last slide |
+
+### OnboardingSlide Interface
+
+```typescript
+interface OnboardingSlide {
+  id: string;
+  type?: 'info' | 'question' | 'welcome' | 'completion';
+  title: string;
+  description: string;
+  icon: string; // Emoji or Lucide icon name
+  gradient: string[]; // [startColor, endColor] or [color1, color2, color3]
+  image?: string;
+  features?: string[];
+  question?: OnboardingQuestion;
+  skipIf?: (answers: Record<string, any>) => boolean;
+}
+```
+
+### Question Types
+
+#### Single Choice
+
+```typescript
+{
+  type: 'single_choice',
+  question: 'What is your goal?',
+  options: [
+    { id: 'weight_loss', label: 'Weight Loss', icon: '🏃' },
+    { id: 'muscle_gain', label: 'Muscle Gain', icon: '💪' },
+  ],
+}
+```
+
+#### Multiple Choice
+
+```typescript
+{
+  type: 'multiple_choice',
+  question: 'Select your interests',
+  validation: { minSelections: 1, maxSelections: 3 },
+  options: [
+    { id: 'yoga', label: 'Yoga', icon: '🧘' },
+    { id: 'running', label: 'Running', icon: '🏃' },
+    { id: 'swimming', label: 'Swimming', icon: '🏊' },
+  ],
+}
+```
+
+#### Text Input
+
+```typescript
+{
+  type: 'text_input',
+  question: 'What is your name?',
+  placeholder: 'Enter your name',
+  validation: { required: true, minLength: 2, maxLength: 50 },
+}
+```
+
+#### Slider
+
+```typescript
+{
+  type: 'slider',
+  question: 'What is your age?',
+  validation: { min: 18, max: 100 },
+  defaultValue: 25,
+}
+```
+
+#### Rating
+
+```typescript
+{
+  type: 'rating',
+  question: 'Rate your experience',
+  validation: { max: 5 },
+}
+```
+
+## 🎨 Customization
+
+### Custom Header
+
+```tsx
+<OnboardingScreen
+  slides={slides}
+  renderHeader={({ isFirstSlide, onBack, onSkip }) => (
+    <View>
+      {!isFirstSlide && <Button onPress={onBack}>Back</Button>}
+      <Button onPress={onSkip}>Skip</Button>
+    </View>
+  )}
+/>
+```
+
+### Custom Footer
+
+```tsx
+<OnboardingScreen
+  slides={slides}
+  renderFooter={({ currentIndex, totalSlides, isLastSlide, onNext }) => (
+    <View>
+      <Text>{currentIndex + 1} / {totalSlides}</Text>
+      <Button onPress={onNext}>
+        {isLastSlide ? 'Get Started' : 'Next'}
+      </Button>
+    </View>
+  )}
+/>
+```
+
+### Conditional Slides
+
+```tsx
+{
+  id: '3',
+  title: 'Advanced Features',
+  description: 'Only for experienced users',
+  icon: '⚡',
+  gradient: ['#667eea', '#764ba2'],
+  skipIf: (answers) => answers.experience_level === 'beginner',
+}
+```
+
+## 💾 Accessing User Data
+
+```tsx
+import { useOnboarding } from '@umituz/react-native-onboarding';
+
+const { userData, getAnswer } = useOnboarding();
+
+// Get specific answer
+const experienceLevel = getAnswer('experience_level');
+
+// Get all answers
+const allAnswers = userData.answers;
+
+// Check if onboarding was completed
+const isComplete = userData.completedAt !== undefined;
+
+// Check if onboarding was skipped
+const wasSkipped = userData.skipped === true;
+```
+
+## 🔄 Resetting Onboarding
+
+```tsx
+import { useOnboarding } from '@umituz/react-native-onboarding';
+
+const { reset } = useOnboarding();
+
+// Reset onboarding (useful for testing or settings)
+await reset();
+```
+
+## 📱 Platform Support
+
+- ✅ iOS
+- ✅ Android
+- ✅ Web
+
+## 🏗️ Architecture
+
+Built with Domain-Driven Design (DDD):
+
+- **Domain Layer**: Entities and interfaces (business logic)
+- **Infrastructure Layer**: Storage and hooks (state management)
+- **Presentation Layer**: Components and screens (UI)
+
+## 📄 License
+
+MIT
+
+## 🤝 Contributing
+
+Contributions are welcome! Please open an issue or PR.
+
+## 📧 Support
+
+For issues and questions, please open an issue on GitHub.
+

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@umituz/react-native-onboarding",
-  "version": "1.0.9",
-  "description": "Generic onboarding flow for React Native apps with gradient backgrounds, animations, and customizable slides. SOLID, DRY, KISS principles applied.",
+  "version": "2.0.0",
+  "description": "Advanced onboarding flow for React Native apps with personalization questions, gradient backgrounds, animations, and customizable slides. SOLID, DRY, KISS principles applied.",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "scripts": {
@@ -35,10 +35,13 @@
     "@umituz/react-native-localization": "latest",
     "@umituz/react-native-design-system-theme": "latest",
     "@umituz/react-native-design-system": "latest",
+    "@umituz/react-native-design-system-atoms": "latest",
+    "@react-native-community/slider": "^4.5.0",
     "expo-linear-gradient": "^15.0.0",
     "react": ">=18.2.0",
     "react-native": ">=0.74.0",
-    "react-native-safe-area-context": "^5.0.0"
+    "react-native-safe-area-context": "^5.0.0",
+    "zustand": "^5.0.0"
   },
   "devDependencies": {
     "@types/react": "^18.2.45",
@@ -46,10 +49,13 @@
     "@umituz/react-native-storage": "^1.1.0",
     "@umituz/react-native-localization": "latest",
     "@umituz/react-native-design-system-theme": "latest",
+    "@umituz/react-native-design-system-atoms": "latest",
+    "@react-native-community/slider": "^4.5.0",
     "expo-linear-gradient": "^15.0.7",
     "react": "^18.2.0",
     "react-native": "^0.74.0",
     "react-native-safe-area-context": "^5.6.0",
+    "zustand": "^5.0.0",
     "typescript": "^5.3.3"
   },
   "publishConfig": {

package/src/domain/entities/OnboardingQuestion.ts

@@ -0,0 +1,156 @@
+/**
+ * Onboarding Question Entity
+ *
+ * Domain entity representing a personalization question in the onboarding flow
+ */
+
+/**
+ * Question types for different input methods
+ */
+export type QuestionType =
+  | "single_choice" // Radio buttons - single selection
+  | "multiple_choice" // Checkboxes - multiple selections
+  | "text_input" // Text input field
+  | "slider" // Slider for numeric values
+  | "rating" // Star rating or numeric rating
+  | "date" // Date picker
+  | "image_picker"; // Image selection from gallery
+
+/**
+ * Option for single/multiple choice questions
+ */
+export interface QuestionOption {
+  /**
+   * Unique identifier for the option
+   */
+  id: string;
+
+  /**
+   * Display label for the option
+   */
+  label: string;
+
+  /**
+   * Optional icon (emoji or Lucide icon name)
+   */
+  icon?: string;
+
+  /**
+   * Optional image URL
+   */
+  image?: string;
+
+  /**
+   * Optional value (if different from label)
+   */
+  value?: string;
+}
+
+/**
+ * Validation rules for questions
+ */
+export interface QuestionValidation {
+  /**
+   * Is this question required?
+   */
+  required?: boolean;
+
+  /**
+   * Minimum value (for slider/rating)
+   */
+  min?: number;
+
+  /**
+   * Maximum value (for slider/rating)
+   */
+  max?: number;
+
+  /**
+   * Minimum length (for text input)
+   */
+  minLength?: number;
+
+  /**
+   * Maximum length (for text input)
+   */
+  maxLength?: number;
+
+  /**
+   * Minimum selections (for multiple choice)
+   */
+  minSelections?: number;
+
+  /**
+   * Maximum selections (for multiple choice)
+   */
+  maxSelections?: number;
+
+  /**
+   * Custom validation function
+   */
+  customValidator?: (value: any) => boolean | string;
+}
+
+/**
+ * Onboarding Question
+ * Represents a personalization question in the onboarding flow
+ */
+export interface OnboardingQuestion {
+  /**
+   * Unique identifier for the question
+   */
+  id: string;
+
+  /**
+   * Question type
+   */
+  type: QuestionType;
+
+  /**
+   * Question text
+   */
+  question: string;
+
+  /**
+   * Optional subtitle/description
+   */
+  subtitle?: string;
+
+  /**
+   * Optional placeholder text (for text input)
+   */
+  placeholder?: string;
+
+  /**
+   * Options for single/multiple choice questions
+   */
+  options?: QuestionOption[];
+
+  /**
+   * Validation rules
+   */
+  validation?: QuestionValidation;
+
+  /**
+   * Default value
+   */
+  defaultValue?: any;
+
+  /**
+   * Storage key for saving the answer
+   */
+  storageKey: string;
+
+  /**
+   * Optional icon for the question
+   */
+  icon?: string;
+
+  /**
+   * Skip this question if condition is met
+   * @param answers - Previous answers
+   * @returns true to skip, false to show
+   */
+  skipIf?: (answers: Record<string, any>) => boolean;
+}
+

package/src/domain/entities/OnboardingSlide.ts

@@ -4,6 +4,13 @@
  * Domain entity representing a single onboarding slide
  */
 
+import type { OnboardingQuestion } from "./OnboardingQuestion";
+
+/**
+ * Slide type - determines the content and behavior
+ */
+export type SlideType = "info" | "question" | "welcome" | "completion";
+
 /**
  * Onboarding Slide
  * Each slide represents one step in the onboarding flow
@@ -14,6 +21,11 @@ export interface OnboardingSlide {
    */
   id: string;
 
+  /**
+   * Slide type (default: "info")
+   */
+  type?: SlideType;
+
   /**
    * Slide title
    */
@@ -44,5 +56,18 @@ export interface OnboardingSlide {
    * Optional features list to display
    */
   features?: string[];
+
+  /**
+   * Optional question for personalization
+   * Only used when type is "question"
+   */
+  question?: OnboardingQuestion;
+
+  /**
+   * Skip this slide if condition is met
+   * @param answers - Previous answers
+   * @returns true to skip, false to show
+   */
+  skipIf?: (answers: Record<string, any>) => boolean;
 }
 

package/src/domain/entities/OnboardingUserData.ts

@@ -0,0 +1,43 @@
+/**
+ * Onboarding User Data Entity
+ *
+ * Domain entity representing collected user data from onboarding
+ */
+
+/**
+ * User data collected during onboarding
+ */
+export interface OnboardingUserData {
+  /**
+   * User's answers to questions
+   * Key: question ID, Value: answer
+   */
+  answers: Record<string, any>;
+
+  /**
+   * Timestamp when onboarding was completed
+   */
+  completedAt?: string;
+
+  /**
+   * Was onboarding skipped?
+   */
+  skipped?: boolean;
+
+  /**
+   * User preferences derived from answers
+   */
+  preferences?: Record<string, any>;
+
+  /**
+   * User profile data
+   */
+  profile?: {
+    name?: string;
+    email?: string;
+    age?: number;
+    gender?: string;
+    [key: string]: any;
+  };
+}
+

package/src/index.ts

@@ -30,8 +30,15 @@
 // DOMAIN LAYER - Entities and Interfaces
 // =============================================================================
 
-export type { OnboardingSlide } from "./domain/entities/OnboardingSlide";
+export type { OnboardingSlide, SlideType } from "./domain/entities/OnboardingSlide";
 export type { OnboardingOptions } from "./domain/entities/OnboardingOptions";
+export type {
+  OnboardingQuestion,
+  QuestionType,
+  QuestionOption,
+  QuestionValidation,
+} from "./domain/entities/OnboardingQuestion";
+export type { OnboardingUserData } from "./domain/entities/OnboardingUserData";
 
 // =============================================================================
 // INFRASTRUCTURE LAYER - Storage and Hooks
@@ -62,3 +69,19 @@ import { OnboardingSlide as OnboardingSlideComponent } from "./presentation/comp
 export { OnboardingSlideComponent };
 export type { OnboardingSlideProps } from "./presentation/components/OnboardingSlide";
 
+// Export QuestionSlide component
+export { QuestionSlide } from "./presentation/components/QuestionSlide";
+export type { QuestionSlideProps } from "./presentation/components/QuestionSlide";
+
+// Export question components
+export { SingleChoiceQuestion } from "./presentation/components/questions/SingleChoiceQuestion";
+export type { SingleChoiceQuestionProps } from "./presentation/components/questions/SingleChoiceQuestion";
+export { MultipleChoiceQuestion } from "./presentation/components/questions/MultipleChoiceQuestion";
+export type { MultipleChoiceQuestionProps } from "./presentation/components/questions/MultipleChoiceQuestion";
+export { TextInputQuestion } from "./presentation/components/questions/TextInputQuestion";
+export type { TextInputQuestionProps } from "./presentation/components/questions/TextInputQuestion";
+export { SliderQuestion } from "./presentation/components/questions/SliderQuestion";
+export type { SliderQuestionProps } from "./presentation/components/questions/SliderQuestion";
+export { RatingQuestion } from "./presentation/components/questions/RatingQuestion";
+export type { RatingQuestionProps } from "./presentation/components/questions/RatingQuestion";
+