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

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';

package/src/onboarding/infrastructure/hooks/__tests__/useOnboardingAnswers.test.ts

@@ -0,0 +1,163 @@
+/**
+ * OnboardingAnswers Hook Tests
+ */
+
+import { renderHook, act } from '@testing-library/react-native';
+import { useOnboardingAnswers } from '../useOnboardingAnswers';
+import { useOnboardingStore } from '../../storage/OnboardingStore';
+
+// Mock the store
+jest.mock('../../storage/OnboardingStore', () => ({
+  useOnboardingStore: jest.fn(),
+}));
+
+const mockUseOnboardingStore = useOnboardingStore as jest.MockedFunction<typeof useOnboardingStore>;
+
+describe('useOnboardingAnswers', () => {
+  const mockGetAnswer = jest.fn();
+  const mockSaveAnswer = jest.fn();
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockUseOnboardingStore.mockReturnValue({
+      getAnswer: mockGetAnswer,
+      saveAnswer: mockSaveAnswer,
+    } as any);
+  });
+
+  it('should initialize with undefined answer', () => {
+    const mockSlide = {
+      id: '1',
+      type: 'question',
+      question: {
+        id: 'q1',
+        type: 'single',
+        text: 'Test question',
+      },
+    };
+
+    const { result } = renderHook(() => useOnboardingAnswers(mockSlide));
+
+    expect(result.current.currentAnswer).toBeUndefined();
+    expect(mockGetAnswer).toHaveBeenCalledWith('q1');
+  });
+
+  it('should load saved answer for slide', () => {
+    const mockSlide = {
+      id: '1',
+      type: 'question',
+      question: {
+        id: 'q1',
+        type: 'single',
+        text: 'Test question',
+      },
+    };
+
+    mockGetAnswer.mockReturnValue('option1');
+
+    const { result } = renderHook(() => useOnboardingAnswers(mockSlide));
+
+    expect(result.current.currentAnswer).toBe('option1');
+  });
+
+  it('should use default value when no saved answer', () => {
+    const mockSlide = {
+      id: '1',
+      type: 'question',
+      question: {
+        id: 'q1',
+        type: 'single',
+        text: 'Test question',
+        defaultValue: 'default',
+      },
+    };
+
+    mockGetAnswer.mockReturnValue(undefined);
+
+    const { result } = renderHook(() => useOnboardingAnswers(mockSlide));
+
+    expect(result.current.currentAnswer).toBe('default');
+  });
+
+  it('should set current answer', () => {
+    const mockSlide = {
+      id: '1',
+      type: 'question',
+      question: {
+        id: 'q1',
+        type: 'single',
+        text: 'Test question',
+      },
+    };
+
+    const { result } = renderHook(() => useOnboardingAnswers(mockSlide));
+
+    act(() => {
+      result.current.setCurrentAnswer('newAnswer');
+    });
+
+    expect(result.current.currentAnswer).toBe('newAnswer');
+  });
+
+  it('should save answer for slide', async () => {
+    const mockSlide = {
+      id: '1',
+      type: 'question',
+      question: {
+        id: 'q1',
+        type: 'single',
+        text: 'Test question',
+      },
+    };
+
+    mockSaveAnswer.mockResolvedValue(undefined);
+
+    const { result } = renderHook(() => useOnboardingAnswers(mockSlide));
+
+    act(() => {
+      result.current.setCurrentAnswer('answer1');
+    });
+
+    await act(async () => {
+      await result.current.saveCurrentAnswer(mockSlide);
+    });
+
+    expect(mockSaveAnswer).toHaveBeenCalledWith('q1', 'answer1');
+  });
+
+  it('should not save answer for non-question slide', async () => {
+    const mockSlide = {
+      id: '1',
+      type: 'welcome',
+      title: 'Welcome',
+    };
+
+    const { result } = renderHook(() => useOnboardingAnswers(mockSlide));
+
+    await act(async () => {
+      await result.current.saveCurrentAnswer(mockSlide);
+    });
+
+    expect(mockSaveAnswer).not.toHaveBeenCalled();
+  });
+
+  it('should not save undefined answer', async () => {
+    const mockSlide = {
+      id: '1',
+      type: 'question',
+      question: {
+        id: 'q1',
+        type: 'single',
+        text: 'Test question',
+      },
+    };
+
+    const { result } = renderHook(() => useOnboardingAnswers(mockSlide));
+
+    await act(async () => {
+      await result.current.saveCurrentAnswer(mockSlide);
+    });
+
+    expect(mockSaveAnswer).not.toHaveBeenCalled();
+  });
+});

package/src/onboarding/infrastructure/hooks/__tests__/useOnboardingNavigation.test.ts

@@ -0,0 +1,121 @@
+/**
+ * OnboardingNavigation Hook Tests
+ */
+
+import { renderHook, act } from '@testing-library/react-native';
+import { useOnboardingNavigation } from '../useOnboardingNavigation';
+
+describe('useOnboardingNavigation', () => {
+  const mockOnComplete = jest.fn();
+  const mockOnSkip = jest.fn();
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should initialize with first slide', () => {
+    const { result } = renderHook(() =>
+      useOnboardingNavigation(3, mockOnComplete, mockOnSkip)
+    );
+
+    expect(result.current.currentIndex).toBe(0);
+    expect(result.current.isFirstSlide).toBe(true);
+    expect(result.current.isLastSlide).toBe(false);
+  });
+
+  it('should navigate to next slide', () => {
+    const { result } = renderHook(() =>
+      useOnboardingNavigation(3, mockOnComplete, mockOnSkip)
+    );
+
+    act(() => {
+      result.current.goToNext();
+    });
+
+    expect(result.current.currentIndex).toBe(1);
+    expect(result.current.isFirstSlide).toBe(false);
+    expect(result.current.isLastSlide).toBe(false);
+  });
+
+  it('should navigate to previous slide', () => {
+    const { result } = renderHook(() =>
+      useOnboardingNavigation(3, mockOnComplete, mockOnSkip)
+    );
+
+    act(() => {
+      result.current.goToNext();
+    });
+    act(() => {
+      result.current.goToPrevious();
+    });
+
+    expect(result.current.currentIndex).toBe(0);
+    expect(result.current.isFirstSlide).toBe(true);
+  });
+
+  it('should handle last slide correctly', () => {
+    const { result } = renderHook(() =>
+      useOnboardingNavigation(2, mockOnComplete, mockOnSkip)
+    );
+
+    act(() => {
+      result.current.goToNext();
+    });
+
+    expect(result.current.currentIndex).toBe(1);
+    expect(result.current.isLastSlide).toBe(true);
+  });
+
+  it('should not go beyond last slide', () => {
+    const { result } = renderHook(() =>
+      useOnboardingNavigation(2, mockOnComplete, mockOnSkip)
+    );
+
+    act(() => {
+      result.current.goToNext();
+    });
+    act(() => {
+      result.current.goToNext();
+    });
+
+    expect(result.current.currentIndex).toBe(1);
+    expect(result.current.isLastSlide).toBe(true);
+  });
+
+  it('should not go before first slide', () => {
+    const { result } = renderHook(() =>
+      useOnboardingNavigation(2, mockOnComplete, mockOnSkip)
+    );
+
+    act(() => {
+      result.current.goToPrevious();
+    });
+
+    expect(result.current.currentIndex).toBe(0);
+    expect(result.current.isFirstSlide).toBe(true);
+  });
+
+  it('should call onComplete when completing', async () => {
+    const { result } = renderHook(() =>
+      useOnboardingNavigation(1, mockOnComplete, mockOnSkip)
+    );
+
+    await act(async () => {
+      await result.current.complete();
+    });
+
+    expect(mockOnComplete).toHaveBeenCalled();
+  });
+
+  it('should call onSkip when skipping', async () => {
+    const { result } = renderHook(() =>
+      useOnboardingNavigation(1, mockOnComplete, mockOnSkip)
+    );
+
+    await act(async () => {
+      await result.current.skip();
+    });
+
+    expect(mockOnSkip).toHaveBeenCalled();
+  });
+});

package/src/onboarding/infrastructure/hooks/useOnboardingAnswers.ts

@@ -0,0 +1,69 @@
+/**
+ * useOnboardingAnswers Hook
+ *
+ * Manages answer state and operations for onboarding questions
+ * Follows Single Responsibility Principle
+ */
+
+import { useState, useEffect, useCallback } from "react";
+import type { OnboardingSlide } from "../../domain/entities/OnboardingSlide";
+import { useOnboarding } from "../storage/OnboardingStore";
+
+export interface UseOnboardingAnswersReturn {
+  currentAnswer: any;
+  setCurrentAnswer: (answer: any) => void;
+  loadAnswerForSlide: (slide: OnboardingSlide | undefined) => void;
+  saveCurrentAnswer: (slide: OnboardingSlide | undefined) => Promise<void>;
+}
+
+/**
+ * Hook for managing onboarding question answers
+ * @param currentSlide - The current slide being displayed
+ * @returns Answer state and operations
+ */
+export function useOnboardingAnswers(
+  currentSlide: OnboardingSlide | undefined,
+): UseOnboardingAnswersReturn {
+  const onboardingStore = useOnboarding();
+  const [currentAnswer, setCurrentAnswer] = useState<any>(undefined);
+
+  /**
+   * Load answer for a specific slide
+   */
+  const loadAnswerForSlide = useCallback(
+    (slide: OnboardingSlide | undefined) => {
+      if (slide?.question) {
+        const savedAnswer = onboardingStore.getAnswer(slide.question.id);
+        setCurrentAnswer(savedAnswer ?? slide.question.defaultValue);
+      } else {
+        setCurrentAnswer(undefined);
+      }
+    },
+    [onboardingStore],
+  );
+
+  /**
+   * Save current answer for a slide
+   */
+  const saveCurrentAnswer = useCallback(
+    async (slide: OnboardingSlide | undefined) => {
+      if (slide?.question && currentAnswer !== undefined) {
+        await onboardingStore.saveAnswer(slide.question.id, currentAnswer);
+      }
+    },
+    [currentAnswer, onboardingStore],
+  );
+
+  // Load answer when slide changes
+  useEffect(() => {
+    loadAnswerForSlide(currentSlide);
+  }, [currentSlide, loadAnswerForSlide]);
+
+  return {
+    currentAnswer,
+    setCurrentAnswer,
+    loadAnswerForSlide,
+    saveCurrentAnswer,
+  };
+}
+

package/src/onboarding/infrastructure/hooks/useOnboardingNavigation.ts

@@ -0,0 +1,75 @@
+/**
+ * useOnboardingNavigation Hook
+ *
+ * Manages navigation state and callbacks for onboarding flow
+ */
+
+import { useState, useCallback } from "react";
+import { DeviceEventEmitter } from "react-native";
+
+export interface UseOnboardingNavigationReturn {
+  currentIndex: number;
+  goToNext: () => void;
+  goToPrevious: () => void;
+  complete: () => Promise<void>;
+  skip: () => Promise<void>;
+  isLastSlide: boolean;
+  isFirstSlide: boolean;
+}
+
+/**
+ * Hook for managing onboarding navigation
+ *
+ * @param totalSlides - Total number of slides
+ * @param onComplete - Callback when onboarding completes
+ * @param onSkip - Callback when onboarding is skipped
+ * @returns Navigation state and handlers
+ */
+export const useOnboardingNavigation = (
+  totalSlides: number,
+  onComplete?: () => void | Promise<void>,
+  onSkip?: () => void | Promise<void>,
+): UseOnboardingNavigationReturn => {
+  const [currentIndex, setCurrentIndex] = useState(0);
+
+  const goToNext = useCallback(() => {
+    if (currentIndex < totalSlides - 1) {
+      setCurrentIndex(currentIndex + 1);
+    }
+  }, [currentIndex, totalSlides]);
+
+  const goToPrevious = useCallback(() => {
+    if (currentIndex > 0) {
+      setCurrentIndex(currentIndex - 1);
+    }
+  }, [currentIndex]);
+
+  const complete = useCallback(async () => {
+    if (onComplete) {
+      await onComplete();
+    }
+    // Emit event for app-level handling
+     
+    if (__DEV__) console.log("[useOnboardingNavigation] Emitting onboarding-complete event");
+    DeviceEventEmitter.emit("onboarding-complete");
+  }, [onComplete]);
+
+  const skip = useCallback(async () => {
+    if (onSkip) {
+      await onSkip();
+    }
+    // Emit event for app-level handling
+    DeviceEventEmitter.emit("onboarding-complete");
+  }, [onSkip]);
+
+  return {
+    currentIndex,
+    goToNext,
+    goToPrevious,
+    complete,
+    skip,
+    isLastSlide: currentIndex === totalSlides - 1,
+    isFirstSlide: currentIndex === 0,
+  };
+};
+

package/src/onboarding/infrastructure/services/SlideManager.ts

@@ -0,0 +1,53 @@
+/**
+ * Onboarding Slide Service
+ *
+ * Business logic for filtering and processing onboarding slides
+ * Follows Single Responsibility Principle
+ */
+
+import type { OnboardingSlide } from "../../domain/entities/OnboardingSlide";
+import type { OnboardingUserData } from "../../domain/entities/OnboardingUserData";
+
+/**
+ * SlideManager
+ */
+export class SlideManager {
+  /**
+   * Filter slides based on skipIf conditions
+   * @param slides - All available slides
+   * @param userData - User's onboarding data including answers
+   * @returns Filtered slides that should be shown
+   */
+  static filterSlides(
+    slides: OnboardingSlide[] | undefined,
+    userData: OnboardingUserData,
+  ): OnboardingSlide[] {
+    // Safety check: return empty array if slides is undefined or not an array
+    if (!slides || !Array.isArray(slides)) {
+      return [];
+    }
+    return slides.filter((slide) => {
+      if (slide.skipIf) {
+        return !slide.skipIf(userData.answers);
+      }
+      return true;
+    });
+  }
+
+  /**
+   * Get slide at specific index
+   * @param slides - Filtered slides array
+   * @param index - Slide index
+   * @returns Slide at index or undefined
+   */
+  static getSlideAtIndex(
+    slides: OnboardingSlide[],
+    index: number,
+  ): OnboardingSlide | undefined {
+    if (index < 0 || index >= slides.length) {
+      return undefined;
+    }
+    return slides[index];
+  }
+}
+