@umituz/react-native-design-system 2.6.127 → 2.7.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@umituz/react-native-design-system",
-  "version": "2.6.127",
-  "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.7.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/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;
+}

package/src/onboarding/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/onboarding/hooks/useOnboardingFlow.ts

@@ -0,0 +1,50 @@
+/**
+ * Onboarding Flow Hook
+ * Manages onboarding completion state with persistence
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+import { DeviceEventEmitter } from 'react-native';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+const ONBOARDING_KEY = 'onboarding_complete';
+
+export interface UseOnboardingFlowResult {
+  isOnboardingComplete: boolean;
+  completeOnboarding: () => Promise<void>;
+}
+
+export const useOnboardingFlow = (): UseOnboardingFlowResult => {
+  const [isOnboardingComplete, setIsOnboardingComplete] = useState(false);
+
+  // Load persisted state
+  useEffect(() => {
+    const loadPersistedState = async () => {
+      const value = await AsyncStorage.getItem(ONBOARDING_KEY);
+      setIsOnboardingComplete(value === 'true');
+    };
+
+    loadPersistedState();
+
+    const subscription = DeviceEventEmitter.addListener(
+      'onboarding-complete',
+      () => {
+        setIsOnboardingComplete(true);
+        AsyncStorage.setItem(ONBOARDING_KEY, 'true');
+      },
+    );
+
+    return () => subscription.remove();
+  }, []);
+
+  const completeOnboarding = useCallback(async () => {
+    await AsyncStorage.setItem(ONBOARDING_KEY, 'true');
+    setIsOnboardingComplete(true);
+    DeviceEventEmitter.emit('onboarding-complete');
+  }, []);
+
+  return {
+    isOnboardingComplete,
+    completeOnboarding,
+  };
+};

package/src/onboarding/index.ts

@@ -0,0 +1,108 @@
+/**
+ * React Native Onboarding - Public API
+ *
+ * Generic onboarding flow for React Native apps with custom backgrounds,
+ * animations, and customizable slides. Follows SOLID, DRY, KISS principles.
+ *
+ * Architecture:
+ * - Domain: Entities and interfaces (business logic)
+ * - Infrastructure: Storage and hooks (state management)
+ * - Presentation: Components and screens (UI)
+ *
+ * Usage:
+ *   import { OnboardingScreen, OnboardingSlide } from '@umituz/react-native-onboarding';
+ *
+ *   <OnboardingScreen
+ *     slides={[
+ *       {
+ *         id: '1',
+ *         title: 'Welcome',
+ *         description: 'Welcome to the app',
+ *         icon: '🎉',
+ *         backgroundColor: '#3B82F6',
+ *       },
+ *     ]}
+ *     onComplete={() => console.log('Completed')}
+ *   />
+ */
+
+// =============================================================================
+// DOMAIN LAYER - Entities and Interfaces
+// =============================================================================
+
+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
+// =============================================================================
+
+export {
+  useOnboardingStore,
+  useOnboarding,
+} from "./infrastructure/storage/OnboardingStore";
+export type { OnboardingStoreState } from "./infrastructure/storage/OnboardingStoreState";
+export type { OnboardingStoreActions } from "./infrastructure/storage/OnboardingStoreActions";
+export type { OnboardingStoreSelectors } from "./infrastructure/storage/OnboardingStoreSelectors";
+export {
+  useOnboardingNavigation,
+  type UseOnboardingNavigationReturn,
+} from "./infrastructure/hooks/useOnboardingNavigation";
+export {
+  useOnboardingContainerStyle,
+  type UseOnboardingContainerStyleProps,
+  type UseOnboardingContainerStyleReturn,
+} from "./presentation/hooks/useOnboardingContainerStyle";
+
+// =============================================================================
+// PRESENTATION LAYER - Components and Screens
+// =============================================================================
+
+export { OnboardingScreen, type OnboardingScreenProps } from "./presentation/screens/OnboardingScreen";
+export { OnboardingHeader, type OnboardingHeaderProps } from "./presentation/components/OnboardingHeader";
+export { OnboardingFooter, type OnboardingFooterProps } from "./presentation/components/OnboardingFooter";
+export { OnboardingProvider, type OnboardingProviderProps, useOnboardingProvider } from "./presentation/providers/OnboardingProvider";
+export { BackgroundImageCollage, type CollageLayout, type BackgroundImageCollageProps } from "./presentation/components/BackgroundImageCollage";
+export type { OnboardingTheme, OnboardingColors } from "./presentation/types/OnboardingTheme";
+
+// =============================================================================
+// UTILITIES - Helper functions
+// =============================================================================
+
+export { ensureArray, safeIncludes, safeFilter } from "./infrastructure/utils/arrayUtils";
+export type { ImageLayoutItem, LayoutConfig } from "./infrastructure/utils/layouts";
+
+// Export OnboardingSlide component
+// Note: TypeScript doesn't allow exporting both a type and a value with the same name
+// The type is exported above as OnboardingSlide
+// The component is exported here with a different name to avoid conflict
+import { OnboardingSlide as OnboardingSlideComponent } from "./presentation/components/OnboardingSlide";
+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 { RatingQuestion } from "./presentation/components/questions/RatingQuestion";
+export type { RatingQuestionProps } from "./presentation/components/questions/RatingQuestion";
+
+export { OnboardingResetSetting } from "./presentation/components/OnboardingResetSetting";
+export type { OnboardingResetSettingProps } from "./presentation/components/OnboardingResetSetting";
+
+
+export { useOnboardingFlow, type UseOnboardingFlowResult } from './hooks/useOnboardingFlow';