@umituz/react-native-design-system 2.6.128 → 2.8.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@umituz/react-native-design-system",
-  "version": "2.6.128",
-  "description": "Universal design system for React Native apps - Consolidated package with atoms, molecules, organisms, theme, typography, responsive, safe area, exception, infinite scroll, UUID, image, timezone and offline utilities",
+  "version": "2.8.0",
+  "description": "Universal design system for React Native apps - Consolidated package with atoms, molecules, organisms, theme, typography, responsive, safe area, exception, infinite scroll, UUID, image, timezone, offline, and onboarding utilities",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
@@ -22,6 +22,7 @@
     "./image": "./src/image/index.ts",
     "./timezone": "./src/timezone/index.ts",
     "./offline": "./src/offline/index.ts",
+    "./onboarding": "./src/onboarding/index.ts",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -74,6 +75,7 @@
     "expo-network": ">=8.0.0",
     "expo-secure-store": ">=14.0.0",
     "expo-sharing": ">=12.0.0",
+    "expo-video": ">=3.0.0",
     "react": ">=19.0.0",
     "react-native": ">=0.81.0",
     "react-native-gesture-handler": ">=2.20.0",

package/src/exports/onboarding.ts

@@ -0,0 +1,6 @@
+/**
+ * Onboarding Exports
+ * Generic onboarding flow for React Native apps
+ */
+
+export * from '../onboarding';

package/src/index.ts

@@ -101,3 +101,8 @@ export * from './exports/variants';
 // UTILITIES
 // =============================================================================
 export * from './exports/utilities';
+
+// =============================================================================
+// ONBOARDING EXPORTS
+// =============================================================================
+export * from './exports/onboarding';

package/src/molecules/navigation/utils/AppNavigation.ts

@@ -3,58 +3,47 @@ import { NavigationContainerRef, CommonActions, StackActions } from '@react-navi
 export class AppNavigation {
     private static navigationRef: NavigationContainerRef<any> | null = null;
 
-    /**
-     * Set the global navigation reference
-     */
     static setRef(ref: NavigationContainerRef<any> | null): void {
         this.navigationRef = ref;
     }
 
     /**
-     * Set the global navigation reference (alias for setRef)
      * @deprecated Use setRef instead
      */
     static setNavigationRef(ref: NavigationContainerRef<any> | null): void {
         this.setRef(ref);
     }
 
-    /**
-     * Get the global navigation reference
-     */
     static getRef(): NavigationContainerRef<any> | null {
         return this.navigationRef;
     }
 
-    /**
-     * Navigate to a route
-     */
+    static isReady(): boolean {
+        return this.navigationRef?.isReady() ?? false;
+    }
+
+    static canGoBack(): boolean {
+        return this.navigationRef?.canGoBack() ?? false;
+    }
+
     static navigate(name: string, params?: object): void {
         if (this.navigationRef?.isReady()) {
             this.navigationRef.navigate(name, params);
         }
     }
 
-    /**
-     * Push a route onto the stack
-     */
     static push(name: string, params?: object): void {
         if (this.navigationRef?.isReady()) {
             this.navigationRef.dispatch(StackActions.push(name, params));
         }
     }
 
-    /**
-     * Go back to the previous screen
-     */
     static goBack(): void {
         if (this.navigationRef?.isReady() && this.navigationRef.canGoBack()) {
             this.navigationRef.goBack();
         }
     }
 
-    /**
-     * Reset the navigation state
-     */
     static reset(name: string, params?: object): void {
         if (this.navigationRef?.isReady()) {
             this.navigationRef.dispatch(
@@ -66,27 +55,18 @@ export class AppNavigation {
         }
     }
 
-    /**
-     * Replace the current route
-     */
     static replace(name: string, params?: object): void {
         if (this.navigationRef?.isReady()) {
             this.navigationRef.dispatch(StackActions.replace(name, params));
         }
     }
 
-    /**
-    * Navigate to a screen in a nested navigator (e.g. Tab > Stack > Screen)
-    */
     static navigateToNested(parentParams: { screen: string; params?: any }): void {
         if (this.navigationRef?.isReady()) {
             this.navigationRef.navigate(parentParams.screen, parentParams.params);
         }
     }
 
-    /**
-     * Navigate to a screen in the parent navigator
-     */
     static navigateToParent(name: string, params?: object): void {
         if (this.navigationRef?.isReady()) {
             const parent = this.navigationRef.getParent();
@@ -95,4 +75,49 @@ export class AppNavigation {
             }
         }
     }
+
+    static popToTop(): void {
+        if (this.navigationRef?.isReady()) {
+            this.navigationRef.dispatch(StackActions.popToTop());
+        }
+    }
+
+    static pop(count: number = 1): void {
+        if (this.navigationRef?.isReady()) {
+            this.navigationRef.dispatch(StackActions.pop(count));
+        }
+    }
+
+    static getCurrentRoute(): string | undefined {
+        return this.navigationRef?.getCurrentRoute()?.name;
+    }
+
+    static getCurrentParams<T extends object>(): T | undefined {
+        return this.navigationRef?.getCurrentRoute()?.params as T | undefined;
+    }
+
+    static goToSettings(): void {
+        this.navigate('Settings');
+    }
+
+    static goToProfile(): void {
+        this.navigate('Profile');
+    }
+
+    static goToHome(): void {
+        this.navigate('Home');
+    }
+
+    static openModal(name: string, params?: object): void {
+        this.navigateToParent(name, params);
+    }
+
+    static closeModal(): void {
+        if (this.navigationRef?.isReady()) {
+            const parent = this.navigationRef.getParent();
+            if (parent?.canGoBack()) {
+                parent.goBack();
+            }
+        }
+    }
 }

package/src/molecules/splash/hooks/useSplashFlow.ts

@@ -1,12 +1,24 @@
 /**
  * Splash Flow Hook
  * Manages splash screen initialization state
+ *
+ * IMPORTANT: Use isAppReady prop instead of duration for real initialization tracking.
+ * Artificial delays cause poor UX - the splash should transition as soon as app is ready.
  */
 
 import { useState, useEffect } from 'react';
 import { DeviceEventEmitter } from 'react-native';
 
 export interface UseSplashFlowOptions {
+  /**
+   * External readiness signal from app initialization
+   * When true, splash will transition to main content
+   */
+  isAppReady?: boolean;
+  /**
+   * @deprecated Use isAppReady instead. Artificial delays cause poor UX.
+   * Only use for fallback/timeout scenarios.
+   */
   duration?: number;
 }
 
@@ -15,17 +27,31 @@ export interface UseSplashFlowResult {
 }
 
 export const useSplashFlow = (options: UseSplashFlowOptions = {}): UseSplashFlowResult => {
-  const { duration = 1500 } = options;
+  const { isAppReady, duration } = options;
   const [isInitialized, setIsInitialized] = useState(false);
 
   useEffect(() => {
-    const timer = setTimeout(() => {
-      setIsInitialized(true);
-      DeviceEventEmitter.emit('splash-ready');
-    }, duration);
+    // Primary: Use external app ready signal (preferred)
+    if (isAppReady !== undefined) {
+      if (isAppReady && !isInitialized) {
+        setIsInitialized(true);
+        DeviceEventEmitter.emit('splash-ready');
+      }
+      return undefined;
+    }
 
-    return () => clearTimeout(timer);
-  }, [duration]);
+    // Fallback: Use duration timer if isAppReady not provided (legacy support)
+    if (duration !== undefined) {
+      const timer = setTimeout(() => {
+        setIsInitialized(true);
+        DeviceEventEmitter.emit('splash-ready');
+      }, duration);
+
+      return () => clearTimeout(timer);
+    }
+
+    return undefined;
+  }, [isAppReady, duration, isInitialized]);
 
   return { isInitialized };
 };

package/src/onboarding/domain/entities/OnboardingOptions.ts

@@ -0,0 +1,104 @@
+/**
+ * Onboarding Options
+ *
+ * Configuration options for onboarding flow
+ */
+
+import type { OnboardingSlide } from "./OnboardingSlide";
+
+/**
+ * Onboarding Options
+ * Customize the onboarding experience
+ */
+export interface OnboardingOptions {
+  /**
+   * Array of slides to display
+   */
+  slides: OnboardingSlide[];
+
+  /**
+   * Callback when onboarding is completed
+   */
+  onComplete?: () => void | Promise<void>;
+
+  /**
+   * Callback when onboarding is skipped
+   */
+  onSkip?: () => void | Promise<void>;
+
+  /**
+   * Custom skip button text (default: "Skip")
+   */
+  skipButtonText?: string;
+
+  /**
+   * Custom next button text (default: "Next")
+   */
+  nextButtonText?: string;
+
+  /**
+   * Custom get started button text (default: "Get Started")
+   */
+  getStartedButtonText?: string;
+
+  /**
+   * Show skip button (default: true)
+   */
+  showSkipButton?: boolean;
+
+  /**
+   * Show back button (default: true)
+   */
+  showBackButton?: boolean;
+
+  /**
+   * Show progress bar (default: true)
+   */
+  showProgressBar?: boolean;
+
+  /**
+   * Show dots indicator (default: true)
+   */
+  showDots?: boolean;
+
+  /**
+   * Show progress text (default: true)
+   */
+  showProgressText?: boolean;
+
+  /**
+   * Storage key for completion state (default: "@onboarding_completed")
+   */
+  storageKey?: string;
+
+  /**
+   * Auto-complete onboarding on last slide (default: false)
+   */
+  autoComplete?: boolean;
+
+  /**
+   * Callback when user wants to upgrade from onboarding
+   */
+  onUpgrade?: () => void;
+
+  /**
+   * Show paywall modal on onboarding completion (default: false)
+   */
+  showPaywallOnComplete?: boolean;
+
+  /**
+   * Use custom background for all slides (default: false)
+   * When true, all slides will use custom backgrounds if available
+   */
+  useCustomBackground?: boolean;
+
+  /**
+   * Visual theme variant (default: "default")
+   * - default: Standard layout
+   * - card: Content in a card with shadow
+   * - minimal: Clean, text-focused layout
+   * - fullscreen: Immersive fullscreen layout
+   */
+  themeVariant?: "default" | "card" | "minimal" | "fullscreen";
+}
+

package/src/onboarding/domain/entities/OnboardingQuestion.ts

@@ -0,0 +1,165 @@
+/**
+ * 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
+  | "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 Ionicons name)
+   */
+  icon?: string;
+
+  /**
+   * Optional image URL
+   */
+  image?: string;
+
+  /**
+   * Optional value (if different from label)
+   */
+  value?: string;
+
+  /**
+   * Type of icon: 'emoji' or 'icon' (default: 'icon')
+   */
+  iconType?: 'emoji' | 'icon';
+}
+
+/**
+ * Validation rules for questions
+ */
+export interface QuestionValidation {
+  /**
+   * Is this question required?
+   */
+  required?: boolean;
+
+  /**
+   * Minimum value (for rating)
+   */
+  min?: number;
+
+  /**
+   * Maximum value (for 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;
+
+  /**
+   * Type of icon: 'emoji' or 'icon' (default: 'icon')
+   */
+  iconType?: 'emoji' | 'icon';
+
+  /**
+   * 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/onboarding/domain/entities/OnboardingSlide.ts

@@ -0,0 +1,152 @@
+/**
+ * Onboarding Slide Entity
+ *
+ * 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";
+
+/**
+ * Content position - determines where the text content is positioned
+ */
+export type ContentPosition = "center" | "bottom";
+
+/**
+ * Onboarding Slide
+ * Each slide represents one step in the onboarding flow
+ */
+export interface OnboardingSlide {
+  /**
+   * Unique identifier for the slide
+   */
+  id: string;
+
+  /**
+   * Slide type (default: "info")
+   */
+  type?: SlideType;
+
+  /**
+   * Slide title
+   */
+  title: string;
+
+  /**
+   * Slide description/body text
+   */
+  description: string;
+
+  /**
+   * Icon to display (emoji or icon name)
+   */
+  icon?: string;
+
+  /**
+   * Type of icon: 'emoji' or 'icon' (default: 'icon')
+   */
+  iconType?: 'emoji' | 'icon';
+
+  /**
+   * Hide icon even if provided (default: false)
+   */
+  hideIcon?: boolean;
+
+  /**
+   * Content position: 'center' or 'bottom' (default: 'center')
+   */
+  contentPosition?: ContentPosition;
+
+  /**
+   * Background color for the slide background (optional)
+   * Only used if useCustomBackground is true
+   */
+  backgroundColor?: string;
+
+  /**
+   * Use custom background color instead of theme defaults (default: false)
+   * If true and backgroundColor is provided, it will be used
+   */
+  useCustomBackground?: boolean;
+
+  /**
+   * Optional image URL (alternative to icon)
+   */
+  image?: any;
+
+  /**
+   * Optional background image (URL or require path)
+   * Stretches to fill the screen behind content
+   */
+  backgroundImage?: any;
+
+  /**
+   * Optional multiple background images (URLs or require paths)
+   * Displayed in a collage/grid pattern behind content
+   * If provided, takes precedence over single backgroundImage
+   */
+  backgroundImages?: any[];
+
+  /**
+   * Layout pattern for multiple background images
+   * 'grid' - Equal sized grid (auto columns)
+   * 'dense' - Dense grid with many small images (6 columns)
+   * 'masonry' - Pinterest-style masonry layout
+   * 'collage' - Random sizes and positions
+   * 'scattered' - Small randomly placed images
+   * 'tiles' - Fixed size tiles centered
+   * 'honeycomb' - Hexagonal pattern
+   * Default: 'grid'
+   */
+  backgroundImagesLayout?: 'grid' | 'dense' | 'masonry' | 'collage' | 'scattered' | 'tiles' | 'honeycomb';
+
+  /**
+   * Number of columns for grid-based layouts
+   * Only applies to: grid, dense, masonry, tiles
+   */
+  backgroundImagesColumns?: number;
+
+  /**
+   * Gap between images in pixels
+   */
+  backgroundImagesGap?: number;
+
+  /**
+   * Border radius for images
+   */
+  backgroundImagesBorderRadius?: number;
+
+  /**
+   * Optional background video (URL or require path)
+   * Plays in loop behind content
+   */
+  backgroundVideo?: any;
+
+  /**
+   * Opacity of the overlay color on top of background media
+   * Range: 0.0 to 1.0 (Default: 0.5)
+   */
+  overlayOpacity?: number;
+
+  /**
+   * 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;
+}