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

package/src/onboarding/presentation/hooks/__tests__/useOnboardingContainerStyle.test.ts

@@ -0,0 +1,96 @@
+/**
+ * OnboardingContainerStyle Hook Tests
+ */
+
+import { renderHook } from '@testing-library/react-native';
+import { useOnboardingContainerStyle } from '../useOnboardingContainerStyle';
+
+// Mock theme hook
+jest.mock('@umituz/react-native-design-system', () => ({
+  useAppDesignTokens: jest.fn(),
+}));
+
+// Mock safe area insets
+jest.mock('react-native-safe-area-context', () => ({
+  useSafeAreaInsets: jest.fn(),
+}));
+
+import { useAppDesignTokens } from '@umituz/react-native-design-system';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+
+const mockUseAppDesignTokens = useAppDesignTokens as jest.MockedFunction<typeof useAppDesignTokens>;
+const mockUseSafeAreaInsets = useSafeAreaInsets as jest.MockedFunction<typeof useSafeAreaInsets>;
+
+describe('useOnboardingContainerStyle', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    
+    mockUseSafeAreaInsets.mockReturnValue({
+      top: 44,
+      bottom: 34,
+      left: 0,
+      right: 0,
+    });
+
+    mockUseAppDesignTokens.mockReturnValue({
+      colors: {
+        backgroundPrimary: '#ffffff',
+      },
+    } as any);
+  });
+
+  it('should return container style with custom background disabled', () => {
+    const { result } = renderHook(() =>
+      useOnboardingContainerStyle({ useCustomBackground: false })
+    );
+
+    expect(result.current.containerStyle).toEqual([
+      {
+        paddingTop: 44,
+        backgroundColor: '#ffffff',
+      },
+    ]);
+  });
+
+  it('should return container style with custom background enabled', () => {
+    const { result } = renderHook(() =>
+      useOnboardingContainerStyle({ useCustomBackground: true })
+    );
+
+    expect(result.current.containerStyle).toEqual([
+      {
+        paddingTop: 44,
+        backgroundColor: 'transparent',
+      },
+    ]);
+  });
+
+  it('should use correct top inset', () => {
+    mockUseSafeAreaInsets.mockReturnValue({
+      top: 50,
+      bottom: 34,
+      left: 0,
+      right: 0,
+    });
+
+    const { result } = renderHook(() =>
+      useOnboardingContainerStyle({ useCustomBackground: false })
+    );
+
+    expect(result.current.containerStyle[0].paddingTop).toBe(50);
+  });
+
+  it('should use theme background color', () => {
+    mockUseAppDesignTokens.mockReturnValue({
+      colors: {
+        backgroundPrimary: '#f0f0f0',
+      },
+    } as any);
+
+    const { result } = renderHook(() =>
+      useOnboardingContainerStyle({ useCustomBackground: false })
+    );
+
+    expect(result.current.containerStyle[0].backgroundColor).toBe('#f0f0f0');
+  });
+});

package/src/onboarding/presentation/hooks/useOnboardingContainerStyle.ts

@@ -0,0 +1,37 @@
+/**
+ * useOnboardingContainerStyle Hook
+ * Single Responsibility: Manage container styling for onboarding screen
+ */
+
+import { useMemo } from "react";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { useAppDesignTokens } from "@umituz/react-native-design-system";
+
+export interface UseOnboardingContainerStyleProps {
+  useCustomBackground: boolean;
+}
+
+export interface UseOnboardingContainerStyleReturn {
+  containerStyle: any;
+}
+
+export function useOnboardingContainerStyle({
+  useCustomBackground,
+}: UseOnboardingContainerStyleProps): UseOnboardingContainerStyleReturn {
+  const insets = useSafeAreaInsets();
+  const tokens = useAppDesignTokens();
+
+  const containerStyle = useMemo(
+    () => [
+      {
+        paddingTop: insets.top,
+        backgroundColor: useCustomBackground ? "transparent" : tokens.colors.backgroundPrimary,
+      },
+    ],
+    [insets.top, useCustomBackground, tokens.colors.backgroundPrimary],
+  );
+
+  return {
+    containerStyle,
+  };
+}

package/src/onboarding/presentation/hooks/useOnboardingGestures.ts

@@ -0,0 +1,45 @@
+/**
+ * useOnboardingGestures Hook
+ * Handles swipe gestures for onboarding navigation
+ */
+
+import { useRef } from "react";
+import { PanResponder } from "react-native";
+
+interface UseOnboardingGesturesProps {
+  isFirstSlide: boolean;
+  isAnswerValid: boolean;
+  onNext: () => void;
+  onBack: () => void;
+}
+
+export const useOnboardingGestures = ({
+  isFirstSlide,
+  isAnswerValid,
+  onNext,
+  onBack,
+}: UseOnboardingGesturesProps) => {
+  const panResponder = useRef(
+    PanResponder.create({
+      onMoveShouldSetPanResponder: (_, gestureState) => {
+        // Only trigger for horizontal swipes
+        return Math.abs(gestureState.dx) > 20 && Math.abs(gestureState.dy) < 40;
+      },
+      onPanResponderRelease: (_, gestureState) => {
+        if (gestureState.dx > 50) {
+          // Swipe Right -> Previous
+          if (!isFirstSlide) {
+            onBack();
+          }
+        } else if (gestureState.dx < -50) {
+          // Swipe Left -> Next
+          if (isAnswerValid) {
+            onNext();
+          }
+        }
+      },
+    })
+  ).current;
+
+  return panResponder;
+};

package/src/onboarding/presentation/hooks/useOnboardingScreenHandlers.ts

@@ -0,0 +1,114 @@
+/**
+ * useOnboardingScreenHandlers Hook
+ * Single Responsibility: Handle onboarding screen user interactions
+ */
+
+import { useCallback } from "react";
+import type { OnboardingSlide } from "../../domain/entities/OnboardingSlide";
+import { SlideManager } from "../../infrastructure/services/SlideManager";
+
+export interface UseOnboardingScreenHandlersProps {
+  filteredSlides: OnboardingSlide[];
+  currentSlide: OnboardingSlide | undefined;
+  currentIndex: number;
+  isLastSlide: boolean;
+  saveCurrentAnswer: (slide: OnboardingSlide) => Promise<void>;
+  completeOnboarding: () => Promise<void>;
+  goToNext: () => void;
+  goToPrevious: () => void;
+  skipOnboarding: () => Promise<void>;
+  loadAnswerForSlide: (slide: OnboardingSlide) => void;
+}
+
+export interface UseOnboardingScreenHandlersReturn {
+  handleNext: () => Promise<void>;
+  handlePrevious: () => void;
+  handleSkip: () => Promise<void>;
+}
+
+export function useOnboardingScreenHandlers({
+  filteredSlides,
+  currentSlide,
+  currentIndex,
+  isLastSlide,
+  saveCurrentAnswer,
+  completeOnboarding,
+  goToNext,
+  goToPrevious,
+  skipOnboarding,
+  loadAnswerForSlide,
+}: UseOnboardingScreenHandlersProps): UseOnboardingScreenHandlersReturn {
+  const handleNext = useCallback(async () => {
+    if (!currentSlide) return;
+
+    try {
+      await saveCurrentAnswer(currentSlide);
+
+      if (isLastSlide) {
+        await completeOnboarding();
+      } else {
+        goToNext();
+
+        const nextSlide = SlideManager.getSlideAtIndex(
+          filteredSlides,
+          currentIndex + 1
+        );
+
+        if (nextSlide) {
+          loadAnswerForSlide(nextSlide);
+        }
+      }
+    } catch (error) {
+      if (__DEV__) {
+        console.error("[useOnboardingScreenHandlers] Error in handleNext:", error);
+      }
+    }
+  }, [
+    currentSlide,
+    isLastSlide,
+    saveCurrentAnswer,
+    completeOnboarding,
+    goToNext,
+    filteredSlides,
+    currentIndex,
+    loadAnswerForSlide,
+  ]);
+
+  const handlePrevious = useCallback(() => {
+    try {
+      goToPrevious();
+
+      const prevSlide = SlideManager.getSlideAtIndex(
+        filteredSlides,
+        currentIndex - 1
+      );
+
+      if (prevSlide) {
+        loadAnswerForSlide(prevSlide);
+      }
+    } catch (error) {
+      if (__DEV__) {
+        console.error(
+          "[useOnboardingScreenHandlers] Error in handlePrevious:",
+          error
+        );
+      }
+    }
+  }, [goToPrevious, filteredSlides, currentIndex, loadAnswerForSlide]);
+
+  const handleSkip = useCallback(async () => {
+    try {
+      await skipOnboarding();
+    } catch (error) {
+      if (__DEV__) {
+        console.error("[useOnboardingScreenHandlers] Error in handleSkip:", error);
+      }
+    }
+  }, [skipOnboarding]);
+
+  return {
+    handleNext,
+    handlePrevious,
+    handleSkip,
+  };
+}

package/src/onboarding/presentation/hooks/useOnboardingScreenState.ts

@@ -0,0 +1,146 @@
+/**
+ * useOnboardingScreenState Hook
+ * Single Responsibility: Coordinate onboarding screen state
+ */
+
+import { useMemo, useEffect } from "react";
+import type { OnboardingSlide } from "../../domain/entities/OnboardingSlide";
+import { useOnboarding } from "../../infrastructure/storage/OnboardingStore";
+import { useOnboardingNavigation } from "../../infrastructure/hooks/useOnboardingNavigation";
+import { useOnboardingAnswers } from "../../infrastructure/hooks/useOnboardingAnswers";
+import { useOnboardingContainerStyle } from "./useOnboardingContainerStyle";
+import { useOnboardingScreenHandlers } from "./useOnboardingScreenHandlers";
+import { SlideManager } from "../../infrastructure/services/SlideManager";
+import { ValidationManager } from "../../infrastructure/services/ValidationManager";
+import { shouldUseCustomBackground } from "../../infrastructure/utils/backgroundUtils";
+
+export interface UseOnboardingScreenStateProps {
+  slides: OnboardingSlide[] | undefined;
+  storageKey?: string;
+  onComplete?: () => void | Promise<void>;
+  onSkip?: () => void | Promise<void>;
+  globalUseCustomBackground?: boolean;
+}
+
+export interface UseOnboardingScreenStateReturn {
+  filteredSlides: OnboardingSlide[];
+  currentSlide: OnboardingSlide | undefined;
+  currentIndex: number;
+  isFirstSlide: boolean;
+  isLastSlide: boolean;
+  currentAnswer: unknown;
+  isAnswerValid: boolean;
+  useCustomBackground: boolean;
+  containerStyle: unknown;
+  handleNext: () => Promise<void>;
+  handlePrevious: () => void;
+  handleSkip: () => Promise<void>;
+  setCurrentAnswer: (value: unknown) => void;
+}
+
+export function useOnboardingScreenState({
+  slides,
+  storageKey,
+  onComplete,
+  onSkip,
+  globalUseCustomBackground = false,
+}: UseOnboardingScreenStateProps): UseOnboardingScreenStateReturn {
+  const onboardingStore = useOnboarding();
+
+  const filteredSlides = useMemo(() => {
+    if (!slides || !Array.isArray(slides) || slides.length === 0) {
+      return [];
+    }
+    const userData = onboardingStore.userData;
+    return SlideManager.filterSlides(slides, userData);
+  }, [slides, onboardingStore.userData]);
+
+  const {
+    currentIndex,
+    goToNext,
+    goToPrevious,
+    complete: completeOnboarding,
+    skip: skipOnboarding,
+    isLastSlide,
+    isFirstSlide,
+  } = useOnboardingNavigation(
+    filteredSlides.length,
+    async () => {
+      await onboardingStore.complete(storageKey);
+      if (onComplete) {
+        await onComplete();
+      }
+    },
+    async () => {
+      await onboardingStore.skip(storageKey);
+      if (onSkip) {
+        await onSkip();
+      }
+    }
+  );
+
+  const currentSlide = useMemo(
+    () => SlideManager.getSlideAtIndex(filteredSlides, currentIndex),
+    [filteredSlides, currentIndex]
+  );
+
+  const {
+    currentAnswer,
+    setCurrentAnswer,
+    loadAnswerForSlide,
+    saveCurrentAnswer,
+  } = useOnboardingAnswers(currentSlide);
+
+  const { handleNext, handlePrevious, handleSkip } = useOnboardingScreenHandlers(
+    {
+      filteredSlides,
+      currentSlide,
+      currentIndex,
+      isLastSlide,
+      saveCurrentAnswer,
+      completeOnboarding,
+      goToNext,
+      goToPrevious,
+      skipOnboarding,
+      loadAnswerForSlide,
+    }
+  );
+
+  const useCustomBackground = shouldUseCustomBackground(currentSlide, globalUseCustomBackground);
+
+  const isAnswerValid = useMemo(() => {
+    if (!currentSlide?.question) {
+      return true;
+    }
+    return ValidationManager.validateAnswer(
+      currentSlide.question,
+      currentAnswer
+    );
+  }, [currentSlide, currentAnswer]);
+
+  const { containerStyle } = useOnboardingContainerStyle({ useCustomBackground });
+
+  useEffect(() => {
+    return () => {
+      if (__DEV__) {
+        console.log("[useOnboardingScreenState] Cleanup completed");
+      }
+    };
+  }, []);
+
+  return {
+    filteredSlides,
+    currentSlide,
+    currentIndex,
+    isFirstSlide,
+    isLastSlide,
+    currentAnswer,
+    isAnswerValid,
+    useCustomBackground,
+    containerStyle,
+    handleNext,
+    handlePrevious,
+    handleSkip,
+    setCurrentAnswer,
+  };
+}

package/src/onboarding/presentation/providers/OnboardingProvider.tsx

@@ -0,0 +1,51 @@
+/**
+ * Onboarding Provider
+ * 
+ * Central manager for onboarding theme and configuration.
+ * All values are passed from the main application.
+ */
+
+import React, { createContext, useContext, useMemo } from "react";
+import type { OnboardingTheme, OnboardingColors } from "../types/OnboardingTheme";
+
+interface OnboardingProviderValue {
+  theme: OnboardingTheme;
+}
+
+const OnboardingScope = createContext<OnboardingProviderValue | undefined>(undefined);
+
+export interface OnboardingProviderProps {
+  children: React.ReactNode;
+  useCustomBackground: boolean;
+  colors: OnboardingColors;
+}
+
+export const OnboardingProvider = ({
+  children,
+  useCustomBackground,
+  colors,
+}: OnboardingProviderProps) => {
+  const value = useMemo(
+    () => ({
+      theme: {
+        colors,
+        useCustomBackground,
+      },
+    }),
+    [colors, useCustomBackground]
+  );
+
+  return (
+    <OnboardingScope.Provider value={value}>
+      {children}
+    </OnboardingScope.Provider>
+  );
+};
+
+export const useOnboardingProvider = (): OnboardingProviderValue => {
+  const scope = useContext(OnboardingScope);
+  if (!scope) {
+    throw new Error("useOnboardingProvider must be used within OnboardingProvider");
+  }
+  return scope;
+};

package/src/onboarding/presentation/screens/OnboardingScreen.tsx

@@ -0,0 +1,189 @@
+/**
+ * Onboarding Screen
+ *
+ * Main onboarding screen component with theme-aware colors
+ * Generic and reusable across hundreds of apps
+ *
+ * This component only handles UI coordination - no business logic
+ */
+
+import React, { useMemo } from "react";
+import { StyleSheet } from "react-native";
+import { useAppDesignTokens } from "@umituz/react-native-design-system";
+import type { OnboardingOptions } from "../../domain/entities/OnboardingOptions";
+import { useOnboardingScreenState } from "../hooks/useOnboardingScreenState";
+import { OnboardingScreenContent } from "../components/OnboardingScreenContent";
+import { OnboardingProvider } from "../providers/OnboardingProvider";
+import type { OnboardingColors } from "../types/OnboardingTheme";
+
+export interface OnboardingScreenProps extends OnboardingOptions {
+  /**
+   * Optional custom header component
+   */
+  renderHeader?: (props: {
+    isFirstSlide: boolean;
+    onBack: () => void;
+    onSkip: () => void;
+  }) => React.ReactNode;
+
+  /**
+   * Optional custom footer component
+   */
+  renderFooter?: (props: {
+    currentIndex: number;
+    totalSlides: number;
+    isLastSlide: boolean;
+    onNext: () => void;
+    onUpgrade?: () => void;
+    showPaywallOnComplete?: boolean;
+  }) => React.ReactNode;
+
+  /**
+   * Optional custom slide component
+   */
+  renderSlide?: (slide: OnboardingOptions["slides"][0]) => React.ReactNode;
+
+  /**
+   * Optional upgrade callback for premium features
+   * Called when user wants to upgrade from onboarding
+   */
+  onUpgrade?: () => void;
+
+  /**
+   * Show paywall modal on onboarding completion (default: false)
+   * When true, shows premium paywall before completing onboarding
+   */
+  showPaywallOnComplete?: boolean;
+
+  /**
+   * Theme colors for the onboarding (Optional - will use design tokens if not provided)
+   */
+  themeColors?: OnboardingColors;
+}
+
+export const OnboardingScreen = ({
+  slides,
+  onComplete,
+  onSkip,
+  skipButtonText,
+  nextButtonText,
+  getStartedButtonText,
+  showSkipButton = true,
+  showBackButton = true,
+  showProgressBar = true,
+  showDots = true,
+  showProgressText = true,
+  storageKey,
+  autoComplete: _autoComplete = false,
+  renderHeader,
+  renderFooter,
+  renderSlide,
+  onUpgrade,
+  showPaywallOnComplete = false,
+  useCustomBackground: globalUseCustomBackground = false,
+  themeVariant = "default",
+  themeColors: providedThemeColors,
+}: OnboardingScreenProps) => {
+  if (__DEV__) {
+    console.log("[OnboardingScreen] Rendering with slides:", slides?.length);
+  }
+
+  const tokens = useAppDesignTokens();
+
+  const themeColors = useMemo(
+    () =>
+      providedThemeColors ?? {
+        iconColor: tokens.colors.primary,
+        textColor: tokens.colors.textPrimary,
+        subTextColor: tokens.colors.textSecondary,
+        buttonBg: tokens.colors.primary,
+        buttonTextColor: tokens.colors.onPrimary,
+        progressBarBg: tokens.colors.surfaceSecondary,
+        progressFillColor: tokens.colors.primary,
+        dotColor: tokens.colors.surfaceSecondary,
+        activeDotColor: tokens.colors.primary,
+        progressTextColor: tokens.colors.textSecondary,
+        headerButtonBg: tokens.colors.surface,
+        headerButtonBorder: tokens.colors.borderLight,
+        iconBg: tokens.colors.surfaceSecondary,
+        iconBorder: tokens.colors.borderLight,
+        errorColor: tokens.colors.error,
+        featureItemBg: tokens.colors.surfaceSecondary,
+      },
+    [providedThemeColors, tokens]
+  );
+
+  const {
+    filteredSlides,
+    currentSlide,
+    currentIndex,
+    isFirstSlide,
+    isLastSlide,
+    currentAnswer,
+    isAnswerValid,
+    useCustomBackground,
+    containerStyle,
+    handleNext,
+    handlePrevious,
+    handleSkip,
+    setCurrentAnswer,
+  } = useOnboardingScreenState({
+    slides,
+    storageKey,
+    onComplete,
+    onSkip,
+    globalUseCustomBackground,
+  });
+
+  if (__DEV__) {
+    console.log("[OnboardingScreen] filteredSlides:", filteredSlides?.length);
+  }
+
+  // Early return if no slides - prevents rendering empty/broken screen
+  if (filteredSlides.length === 0) {
+    if (__DEV__) {
+      console.log("[OnboardingScreen] No slides, returning null");
+    }
+    return null;
+  }
+
+  return (
+    <OnboardingProvider useCustomBackground={useCustomBackground} colors={themeColors}>
+      <OnboardingScreenContent
+        containerStyle={[styles.container, containerStyle]}
+        useCustomBackground={useCustomBackground}
+        currentSlide={currentSlide}
+        isFirstSlide={isFirstSlide}
+        isLastSlide={isLastSlide}
+        currentIndex={currentIndex}
+        totalSlides={filteredSlides.length}
+        currentAnswer={currentAnswer}
+        isAnswerValid={isAnswerValid}
+        showBackButton={showBackButton}
+        showSkipButton={showSkipButton}
+        showProgressBar={showProgressBar}
+        showDots={showDots}
+        showProgressText={showProgressText}
+        skipButtonText={skipButtonText}
+        nextButtonText={nextButtonText}
+        getStartedButtonText={getStartedButtonText}
+        onBack={handlePrevious}
+        onSkip={handleSkip}
+        onNext={handleNext}
+        onAnswerChange={setCurrentAnswer}
+        renderHeader={renderHeader}
+        renderFooter={renderFooter}
+        renderSlide={renderSlide}
+        onUpgrade={onUpgrade}
+        showPaywallOnComplete={showPaywallOnComplete}
+        variant={themeVariant}
+      />
+    </OnboardingProvider>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+});