@umituz/react-native-design-system 4.28.5 → 4.28.7

package/src/onboarding/presentation/components/questions/questionStyles.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared Styles for Question Components
+ * Eliminates code duplication across SingleChoice, MultipleChoice, etc.
+ */
+
+import { StyleSheet } from 'react-native';
+
+export const questionStyles = StyleSheet.create({
+  option: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    borderRadius: 20,
+    padding: 16,
+    marginBottom: 8,
+    width: '100%',
+  },
+  optionIcon: {
+    width: 40,
+    height: 40,
+    borderRadius: 20,
+    alignItems: 'center',
+    justifyContent: 'center',
+    marginRight: 16,
+  },
+  optionLabel: {
+    flex: 1,
+    fontSize: 16,
+  },
+  radioOuter: {
+    width: 24,
+    height: 24,
+    borderRadius: 12,
+    borderWidth: 2,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  radioInner: {
+    width: 12,
+    height: 12,
+    borderRadius: 6,
+  },
+  checkbox: {
+    width: 24,
+    height: 24,
+    borderRadius: 8,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  container: {
+    width: '100%',
+  },
+  hint: {
+    textAlign: 'center',
+    marginTop: 8,
+  },
+});
+
+export const OPTION_ICON_SIZE = 20;
+export const OPTION_EMOJI_SIZE = 24;

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

@@ -0,0 +1,278 @@
+/**
+ * Chat Onboarding Hook
+ *
+ * Core state management for chat-based onboarding flows
+ * Generic and reusable across all apps
+ */
+
+import { useState, useCallback, useRef, useEffect, useMemo } from "react";
+
+import type { ChatStep, ChatOption } from "../../domain/entities/ChatStep";
+import type { ChatMessage } from "../../domain/entities/ChatMessage";
+
+export interface UseChatOnboardingOptions {
+  /** Chat onboarding flow configuration */
+  flow: Record<string, ChatStep>;
+
+  /** Initial step ID (default: first step in flow) */
+  initialStepId?: string;
+
+  /** Callback when onboarding completes */
+  onComplete?: () => void;
+
+  /** Callback when user skips onboarding */
+  onSkip?: () => void;
+
+  /** Delay between messages (ms) */
+  messageDelay?: number;
+
+  /** Store progress persistently */
+  storageKey?: string;
+}
+
+export interface UseChatOnboardingReturn {
+  /** Current chat step */
+  currentStep: ChatStep | null;
+
+  /** Current step ID */
+  currentStepId: string;
+
+  /** Array of chat messages */
+  messages: ChatMessage[];
+
+  /** Whether to show options */
+  showOptions: boolean;
+
+  /** Whether processing user input */
+  isProcessing: boolean;
+
+  /** Whether to show typing indicator */
+  showTypingIndicator: boolean;
+
+  /** Handle option selection */
+  handleOptionSelect: (option: ChatOption) => void;
+
+  /** Reset onboarding flow */
+  handleReset: () => void;
+
+  /** Navigate to specific step */
+  setCurrentStepId: (stepId: string) => void;
+
+  /** Submit name input */
+  handleSubmitName: (name: string) => void;
+
+  /** Skip current step */
+  handleSkip: () => void;
+}
+
+/**
+ * Hook for managing chat onboarding state
+ */
+export const useChatOnboarding = ({
+  flow,
+  initialStepId,
+  onComplete,
+  onSkip,
+  messageDelay = 500,
+}: UseChatOnboardingOptions): UseChatOnboardingReturn => {
+  // Get initial step ID
+  const getInitialStepId = useCallback(() => {
+    if (initialStepId) return initialStepId;
+    const stepIds = Object.keys(flow);
+    return stepIds.length > 0 ? stepIds[0] : "";
+  }, [flow, initialStepId]);
+
+  // State
+  const [currentStepId, setCurrentStepId] = useState<string>(getInitialStepId);
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [showOptions, setShowOptions] = useState<boolean>(false);
+  const [isProcessing, setIsProcessing] = useState<boolean>(false);
+  const [showTypingIndicator, setShowTypingIndicator] = useState<boolean>(false);
+
+  // Refs
+  const messageTimersRef = useRef<NodeJS.Timeout[]>([]);
+  const autoAdvanceTimerRef = useRef<NodeJS.Timeout | null>(null);
+
+  // Memoize current step
+  const currentStep = useMemo(() => {
+    return flow[currentStepId] || null;
+  }, [flow, currentStepId]);
+
+  // Clear all timers
+  const clearTimers = useCallback(() => {
+    messageTimersRef.current.forEach((timer) => {
+      clearTimeout(timer);
+    });
+    messageTimersRef.current = [];
+
+    if (autoAdvanceTimerRef.current) {
+      clearTimeout(autoAdvanceTimerRef.current);
+      autoAdvanceTimerRef.current = null;
+    }
+  }, []);
+
+  // Load messages for current step
+  useEffect(() => {
+    if (!currentStep) return;
+
+    clearTimers();
+    setMessages([]);
+    setShowOptions(false);
+    setShowTypingIndicator(true);
+
+    const timers: NodeJS.Timeout[] = [];
+
+    // Show typing indicator first
+    const hideTypingDelay = currentStep.messages.length > 0 ? 300 : 0;
+    timers.push(
+      setTimeout(() => {
+        setShowTypingIndicator(false);
+      }, hideTypingDelay)
+    );
+
+    // Add messages with staggered delays
+    let accumulatedDelay = hideTypingDelay;
+    currentStep.messages.forEach((msg, index) => {
+      const delay = accumulatedDelay + (index > 0 ? messageDelay : 0);
+      timers.push(
+        setTimeout(() => {
+          setMessages((prev) => [
+            ...prev,
+            {
+              text: msg,
+              isUser: false,
+            },
+          ]);
+        }, delay)
+      );
+      accumulatedDelay = delay + msg.length * 10; // Dynamic delay based on message length
+    });
+
+    // Auto-advance if configured
+    if (currentStep.autoNext) {
+      const autoAdvanceDelay = accumulatedDelay + (currentStep.delay || 2000);
+      const timer = setTimeout(() => {
+        setCurrentStepId(currentStep.autoNext!);
+      }, autoAdvanceDelay);
+      autoAdvanceTimerRef.current = timer;
+    } else {
+      // Show options after messages
+      const optionsDelay = accumulatedDelay + 500;
+      timers.push(
+        setTimeout(() => {
+          if (currentStep.options && currentStep.options.length > 0) {
+            setShowOptions(true);
+          }
+        }, optionsDelay)
+      );
+    }
+
+    messageTimersRef.current = timers;
+
+    return () => {
+      clearTimers();
+    };
+  }, [currentStep, messageDelay, clearTimers]);
+
+  // Handle option selection
+  const handleOptionSelect = useCallback(
+    (option: ChatOption) => {
+      if (isProcessing) return;
+
+      setIsProcessing(true);
+      setShowOptions(false);
+
+      // Add user message
+      setMessages((prev) => [
+        ...prev,
+        {
+          text: option.label,
+          isUser: true,
+        },
+      ]);
+
+      // Navigate to next step
+      setTimeout(() => {
+        setCurrentStepId(option.next);
+        setIsProcessing(false);
+      }, 600);
+    },
+    [isProcessing]
+  );
+
+  // Handle name submission
+  const handleSubmitName = useCallback(
+    (name: string) => {
+      if (!currentStep || isProcessing) return;
+
+      setIsProcessing(true);
+
+      // Skip if empty and allowed
+      if (!name.trim() && currentStep.skipIfEmpty) {
+        setCurrentStepId(currentStep.next || "");
+        setIsProcessing(false);
+        return;
+      }
+
+      // Add user message
+      setMessages((prev) => [
+        ...prev,
+        {
+          text: name.trim(),
+          isUser: true,
+        },
+      ]);
+
+      // Navigate to next step
+      setTimeout(() => {
+        if (currentStep?.next) {
+          setCurrentStepId(currentStep.next);
+        }
+        setIsProcessing(false);
+      }, 600);
+    },
+    [currentStep, isProcessing]
+  );
+
+  // Handle skip
+  const handleSkip = useCallback(() => {
+    clearTimers();
+    onSkip?.();
+  }, [clearTimers, onSkip]);
+
+  // Handle reset
+  const handleReset = useCallback(() => {
+    clearTimers();
+    setCurrentStepId(getInitialStepId());
+    setMessages([]);
+    setShowOptions(false);
+    setIsProcessing(false);
+    setShowTypingIndicator(false);
+  }, [clearTimers, getInitialStepId]);
+
+  // Handle completion
+  useEffect(() => {
+    if (currentStep?.isComplete) {
+      const timer = setTimeout(() => {
+        onComplete?.();
+      }, currentStep.delay || 2000);
+
+      return () => clearTimeout(timer);
+    }
+    return undefined;
+  }, [currentStep, onComplete]);
+
+  return {
+    currentStep,
+    currentStepId,
+    messages,
+    showOptions,
+    isProcessing,
+    showTypingIndicator,
+    handleOptionSelect,
+    handleReset,
+    setCurrentStepId,
+    handleSubmitName,
+    handleSkip,
+  };
+};

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

@@ -0,0 +1,276 @@
+/**
+ * Chat Onboarding Screen
+ *
+ * Chat-based onboarding experience for user engagement
+ * Fully configurable flow, optional mascot, lazy-loaded animations
+ *
+ * Responsive Design:
+ * - Uses useSafeAreaInsets() from react-native-safe-area-context for proper device compatibility
+ * - Flexible flex-based layouts that adapt to all screen sizes
+ * - KeyboardAvoidingView for proper keyboard handling on iOS/Android
+ * - Percentage-based maxWidth in chat messages for responsive text layout
+ * - Proper insets integration with device and safe-area modules
+ *
+ * Compatible with:
+ * - @umituz/react-native-design-system/device (useDeviceInfo)
+ * - @umituz/react-native-design-system/safe-area (useSafeAreaInsets)
+ * - All screen sizes (iPhone, iPad, Android phones/tablets)
+ */
+
+import React, { memo } from "react";
+import {
+  View,
+  StyleSheet,
+  ScrollView,
+  TextInput,
+  TouchableOpacity,
+  KeyboardAvoidingView,
+  Platform,
+  ViewStyle,
+  Text,
+} from "react-native";
+import { useResponsive } from "../../../responsive/useResponsive";
+
+import type { ChatStep } from "../../domain/entities/ChatStep";
+import { useChatOnboarding } from "../hooks/useChatOnboarding";
+import { ChatMessageComponent, ChatOptionButton, TypingIndicator } from "../components/chat";
+
+export interface ChatOnboardingScreenProps {
+  /** Chat onboarding flow configuration */
+  flow: Record<string, ChatStep>;
+
+  /** Initial step ID */
+  initialStepId?: string;
+
+  /** Completion callback */
+  onComplete?: () => void;
+
+  /** Skip callback */
+  onSkip?: () => void;
+
+  /** Show mascot (default: false) */
+  showMascot?: boolean;
+
+  /** Mascot component to render */
+  renderMascot?: (state: string) => React.ReactNode;
+
+  /** Theme colors */
+  theme?: {
+    /** Background color */
+    background?: string;
+
+    /** Message background color */
+    messageBackground?: string;
+
+    /** Message text color */
+    messageText?: string;
+
+    /** User message background color */
+    userMessageBackground?: string;
+
+    /** User message text color */
+    userMessageText?: string;
+
+    /** Button background color */
+    buttonBackground?: string;
+
+    /** Button text color */
+    buttonText?: string;
+
+    /** Button border color */
+    buttonBorder?: string;
+  };
+
+  /** Custom styles */
+  style?: ViewStyle;
+
+  /** Delay between messages */
+  messageDelay?: number;
+
+  /** Render custom icon */
+  renderIcon?: (iconName: string) => React.ReactNode;
+
+  /** Storage key for progress persistence */
+  storageKey?: string;
+}
+
+/**
+ * Chat onboarding screen component
+ */
+export const ChatOnboardingScreen = memo(
+  ({
+    flow,
+    initialStepId,
+    onComplete,
+    onSkip,
+    showMascot = false,
+    renderMascot,
+    theme = {},
+    style,
+    messageDelay = 500,
+    renderIcon,
+  }: ChatOnboardingScreenProps) => {
+    const responsive = useResponsive();
+
+    const {
+      currentStep,
+      messages,
+      showOptions,
+      isProcessing,
+      showTypingIndicator,
+      handleOptionSelect,
+      handleSubmitName,
+    } = useChatOnboarding({
+      flow,
+      initialStepId,
+      onComplete,
+      onSkip,
+      messageDelay,
+    });
+
+    const [nameInput, setNameInput] = React.useState("");
+
+    const handleNameSubmit = () => {
+      handleSubmitName(nameInput);
+      setNameInput("");
+    };
+
+    const containerStyle = [
+      styles.container,
+      {
+        backgroundColor: theme.background || "#FFFFFF",
+        paddingBottom: responsive.insets.bottom + 20,
+        paddingTop: responsive.insets.top + 20,
+      },
+      style,
+    ];
+
+    return (
+      <KeyboardAvoidingView
+        style={containerStyle}
+        behavior={Platform.OS === "ios" ? "padding" : "height"}
+        keyboardVerticalOffset={Platform.OS === "ios" ? 0 : 20}
+      >
+        {/* Mascot Section */}
+        {showMascot && renderMascot && currentStep?.mascotState && (
+          <View style={styles.mascotContainer}>{renderMascot(currentStep.mascotState)}</View>
+        )}
+
+        {/* Messages Section */}
+        <ScrollView
+          style={styles.messagesContainer}
+          contentContainerStyle={styles.messagesContent}
+          showsVerticalScrollIndicator={false}
+        >
+          {messages.map((msg, index) => (
+            <ChatMessageComponent
+              key={`${currentStep?.id}-${index}`}
+              message={msg}
+              backgroundColor={theme.messageBackground}
+              textColor={theme.messageText}
+              userBackgroundColor={theme.userMessageBackground}
+              userTextColor={theme.userMessageText}
+            />
+          ))}
+
+          {showTypingIndicator && (
+            <TypingIndicator
+              backgroundColor={theme.messageBackground}
+              dotColor={theme.messageText}
+            />
+          )}
+
+          {/* Options Section */}
+          {showOptions && currentStep?.options && (
+            <View style={styles.optionsContainer}>
+              {currentStep.options.map((option, index) => (
+                <ChatOptionButton
+                  key={`${option.value}-${index}`}
+                  option={option}
+                  onPress={handleOptionSelect}
+                  backgroundColor={theme.buttonBackground}
+                  textColor={theme.buttonText}
+                  borderColor={theme.buttonBorder}
+                  disabled={isProcessing}
+                  renderIcon={renderIcon}
+                />
+              ))}
+            </View>
+          )}
+
+          {/* Name Input Section */}
+          {currentStep?.isNameInput && (
+            <View style={styles.inputContainer}>
+              <TextInput
+                style={[styles.nameInput, { borderColor: theme.buttonBorder }]}
+                placeholder="Enter your name..."
+                placeholderTextColor={theme.messageText}
+                value={nameInput}
+                onChangeText={setNameInput}
+                onSubmitEditing={handleNameSubmit}
+                returnKeyType="done"
+                autoCapitalize="words"
+              />
+              <TouchableOpacity
+                style={[styles.submitButton, { backgroundColor: theme.buttonBackground }]}
+                onPress={handleNameSubmit}
+                disabled={isProcessing || !nameInput.trim()}
+              >
+                <Text style={[styles.submitButtonText, { color: theme.buttonText }]}>Send</Text>
+              </TouchableOpacity>
+            </View>
+          )}
+        </ScrollView>
+      </KeyboardAvoidingView>
+    );
+  }
+);
+
+ChatOnboardingScreen.displayName = "ChatOnboardingScreen";
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+  mascotContainer: {
+    alignItems: "center",
+    paddingVertical: 20,
+  },
+  messagesContainer: {
+    flex: 1,
+    paddingHorizontal: 16,
+  },
+  messagesContent: {
+    paddingTop: 10,
+  },
+  optionsContainer: {
+    marginTop: 16,
+    marginBottom: 16,
+  },
+  inputContainer: {
+    flexDirection: "row",
+    alignItems: "center",
+    marginTop: 12,
+    marginBottom: 16,
+  },
+  nameInput: {
+    flex: 1,
+    height: 48,
+    borderWidth: 1,
+    borderRadius: 12,
+    paddingHorizontal: 16,
+    fontSize: 16,
+    marginRight: 8,
+  },
+  submitButton: {
+    height: 48,
+    paddingHorizontal: 20,
+    borderRadius: 12,
+    justifyContent: "center",
+    alignItems: "center",
+  },
+  submitButtonText: {
+    fontSize: 16,
+    fontWeight: "600",
+  },
+});

package/src/utils/arrayUtils.ts

@@ -0,0 +1,46 @@
+/**
+ * Array Utilities
+ * Common array manipulation helpers
+ */
+
+/**
+ * Creates an array of specified length and maps over it
+ * Alternative to Array.from({ length }).map() which is more verbose
+ *
+ * @param length - Length of array to create
+ * @param mapFn - Map function (receives index)
+ * @returns Mapped array
+ *
+ * @example
+ * createMappedArray(5, (i) => i * 2) // [0, 2, 4, 6, 8]
+ */
+export function createMappedArray<T>(
+  length: number,
+  mapFn: (index: number) => T
+): T[] {
+  return Array.from({ length }, (_, index) => mapFn(index));
+}
+
+/**
+ * Safely slice array to specified length
+ * Returns empty array if input is null/undefined
+ */
+export function safeSlice<T>(array: T[] | undefined, start: number, end?: number): T[] {
+  if (!array) return [];
+  return array.slice(start, end);
+}
+
+/**
+ * Filter array by ID
+ * Returns new array with item matching ID removed
+ */
+export function filterById<T extends { id: string }>(array: T[], idToRemove: string): T[] {
+  return array.filter(item => item.id !== idToRemove);
+}
+
+/**
+ * Find item in array by ID
+ */
+export function findById<T extends { id: string }>(array: T[], id: string): T | undefined {
+  return array.find(item => item.id === id);
+}

package/src/utils/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Utils Module
+ *
+ * Centralized utility functions for the design system.
+ */
+
+export {
+  calculateResponsiveSize,
+  calculateResponsiveSizes,
+  calculateResponsiveSizeSubtle,
+  calculateLineHeight,
+  createResponsiveSizes,
+} from './responsiveUtils';
+
+export {
+  createMappedArray,
+  safeSlice,
+  filterById,
+  findById,
+} from './arrayUtils';