@umituz/react-native-settings 4.20.61 → 4.21.1

package/src/domains/gamification/hooks/useGamification.ts

@@ -0,0 +1,91 @@
+/**
+ * useGamification Hook
+ * Main hook for gamification operations
+ */
+
+import { useCallback, useEffect, useMemo } from "react";
+import { useGamificationStore } from "../store/gamificationStore";
+import { calculateLevel } from "../utils/calculations";
+import type { GamificationConfig, LevelState, Achievement } from "../types";
+
+export interface UseGamificationReturn {
+  // State
+  points: number;
+  totalTasksCompleted: number;
+  level: LevelState;
+  streak: { current: number; longest: number };
+  achievements: Achievement[];
+  isLoading: boolean;
+  isInitialized: boolean;
+
+  // Actions
+  initialize: (config: GamificationConfig) => Promise<void>;
+  completeTask: () => void;
+  addPoints: (amount: number) => void;
+  reset: () => Promise<void>;
+}
+
+export const useGamification = (
+  config?: GamificationConfig
+): UseGamificationReturn => {
+  const store = useGamificationStore();
+
+  // Auto-initialize if config provided
+  useEffect(() => {
+    if (config && !store.isInitialized) {
+      store.initialize(config);
+    }
+  }, [config, store.isInitialized]);
+
+  // Calculate level from config
+  const level = useMemo((): LevelState => {
+    if (!config?.levels.length) {
+      return {
+        currentLevel: 1,
+        currentPoints: store.points,
+        pointsToNext: 50,
+        progress: Math.min(100, (store.points / 50) * 100),
+      };
+    }
+    return calculateLevel(store.points, config.levels);
+  }, [store.points, config?.levels]);
+
+  const completeTask = useCallback(() => {
+    store.completeTask();
+  }, [store.completeTask]);
+
+  const addPoints = useCallback(
+    (amount: number) => {
+      store.addPoints(amount);
+    },
+    [store.addPoints]
+  );
+
+  const initialize = useCallback(
+    async (cfg: GamificationConfig) => {
+      await store.initialize(cfg);
+    },
+    [store.initialize]
+  );
+
+  const reset = useCallback(async () => {
+    await store.reset();
+  }, [store.reset]);
+
+  return {
+    points: store.points,
+    totalTasksCompleted: store.totalTasksCompleted,
+    level,
+    streak: {
+      current: store.streak.current,
+      longest: store.streak.longest,
+    },
+    achievements: store.achievements,
+    isLoading: store.isLoading,
+    isInitialized: store.isInitialized,
+    initialize,
+    completeTask,
+    addPoints,
+    reset,
+  };
+};

package/src/domains/gamification/index.ts

@@ -0,0 +1,65 @@
+/**
+ * @umituz/react-native-gamification
+ *
+ * Generic gamification system for React Native apps
+ * All text via props - NO hardcoded strings
+ * Designed for 100+ apps
+ */
+
+// Types
+export type {
+  AchievementDefinition,
+  Achievement,
+  LevelDefinition,
+  LevelState,
+  StreakState,
+  GamificationConfig,
+  GamificationState,
+  GamificationActions,
+  GamificationStore,
+} from "./types";
+
+// Settings Integration Types
+export type {
+  GamificationSettingsConfig,
+  GamificationMenuConfig,
+} from "./types/settings";
+
+// Store
+export { useGamificationStore } from "./store/gamificationStore";
+
+// Hooks
+export { useGamification, type UseGamificationReturn } from "./hooks/useGamification";
+
+// Utils
+export {
+  calculateLevel,
+  checkAchievementUnlock,
+  updateAchievementProgress,
+  isStreakActive,
+  isSameDay,
+} from "./utils/calculations";
+
+// Components
+export {
+  LevelProgress,
+  type LevelProgressProps,
+  PointsBadge,
+  type PointsBadgeProps,
+  AchievementCard,
+  type AchievementCardProps,
+  AchievementToast,
+  type AchievementToastProps,
+  StreakDisplay,
+  type StreakDisplayProps,
+  StatsCard,
+  type StatsCardProps,
+  AchievementItem,
+  type AchievementItemProps,
+  GamificationScreen,
+  type GamificationScreenProps,
+} from "./components";
+
+// Settings Integration Components
+export { GamificationScreenWrapper } from "./components/GamificationScreenWrapper";
+export { GamificationSettingsItem } from "./components/GamificationSettingsItem";

package/src/domains/gamification/store/gamificationStore.ts

@@ -0,0 +1,162 @@
+/**
+ * Gamification Store
+ * Zustand store with persist middleware
+ */
+
+import { createStore } from "@umituz/react-native-storage";
+import type {
+  GamificationState,
+  GamificationActions,
+  GamificationConfig,
+  Achievement,
+} from "../types";
+import {
+  checkAchievementUnlock,
+  updateAchievementProgress,
+  isStreakActive,
+  isSameDay,
+} from "../utils/calculations";
+
+const DEFAULT_STATE: GamificationState = {
+  points: 0,
+  totalTasksCompleted: 0,
+  achievements: [],
+  streak: {
+    current: 0,
+    longest: 0,
+    lastActivityDate: null,
+  },
+  isLoading: false,
+  isInitialized: false,
+};
+
+let currentConfig: GamificationConfig | null = null;
+
+export const useGamificationStore = createStore<GamificationState, GamificationActions>({
+  name: "gamification-storage",
+  initialState: DEFAULT_STATE,
+  persist: true,
+  version: 1,
+  partialize: (state) => ({
+    points: state.points,
+    totalTasksCompleted: state.totalTasksCompleted,
+    achievements: state.achievements,
+    streak: state.streak,
+    isLoading: false,
+    isInitialized: false,
+  }),
+  actions: (set, get) => ({
+    initialize: async (config: GamificationConfig) => {
+      currentConfig = config;
+      const state = get();
+
+      // Initialize achievements from config
+      const achievements: Achievement[] = config.achievements.map((def) => ({
+        ...def,
+        isUnlocked: false,
+        progress: 0,
+      }));
+
+      // Merge with existing unlocked achievements
+      const mergedAchievements = achievements.map((ach: Achievement) => {
+        const existing = state.achievements.find((a: Achievement) => a.id === ach.id);
+        if (existing) {
+          return { ...ach, isUnlocked: existing.isUnlocked, progress: existing.progress };
+        }
+        return ach;
+      });
+
+      set({ achievements: mergedAchievements, isInitialized: true });
+    },
+
+    addPoints: (amount: number) => {
+      const state = get();
+      set({ points: state.points + amount });
+    },
+
+    completeTask: () => {
+      const state = get();
+      const pointsToAdd = currentConfig?.pointsPerAction ?? 15;
+
+      set({
+        totalTasksCompleted: state.totalTasksCompleted + 1,
+        points: state.points + pointsToAdd,
+      });
+
+      // Update streak
+      get().updateStreak();
+
+      // Check achievements
+      get().checkAchievements();
+    },
+
+    updateStreak: () => {
+      const state = get();
+      const now = new Date();
+      const lastDate = state.streak.lastActivityDate
+        ? new Date(state.streak.lastActivityDate)
+        : null;
+
+      let newStreak = state.streak.current;
+
+      if (!lastDate || !isSameDay(lastDate, now)) {
+        if (isStreakActive(state.streak.lastActivityDate)) {
+          newStreak = state.streak.current + 1;
+        } else {
+          newStreak = 1;
+        }
+      }
+
+      set({
+        streak: {
+          current: newStreak,
+          longest: Math.max(state.streak.longest, newStreak),
+          lastActivityDate: now.toISOString(),
+        },
+      });
+    },
+
+    checkAchievements: () => {
+      if (!currentConfig) return [];
+
+      const state = get();
+      const newlyUnlocked: Achievement[] = [];
+
+      const updatedAchievements = state.achievements.map((ach: Achievement) => {
+        if (ach.isUnlocked) return ach;
+
+        const progress = updateAchievementProgress(
+          ach,
+          state.totalTasksCompleted,
+          state.streak.current
+        );
+
+        const shouldUnlock = checkAchievementUnlock(
+          ach,
+          state.totalTasksCompleted,
+          state.streak.current
+        );
+
+        if (shouldUnlock && !ach.isUnlocked) {
+          const unlocked = {
+            ...ach,
+            isUnlocked: true,
+            unlockedAt: new Date().toISOString(),
+            progress: 100,
+          };
+          newlyUnlocked.push(unlocked);
+          return unlocked;
+        }
+
+        return { ...ach, progress };
+      });
+
+      set({ achievements: updatedAchievements });
+      return newlyUnlocked;
+    },
+
+    reset: async () => {
+      set(DEFAULT_STATE);
+    },
+  }),
+});

package/src/domains/gamification/types/index.ts

@@ -0,0 +1,103 @@
+/**
+ * Gamification Types
+ * Generic types for 100+ apps - NO app-specific code
+ */
+
+// Achievement Definition (provided by app)
+export interface AchievementDefinition {
+  id: string;
+  threshold: number;
+  type: "count" | "streak" | "milestone";
+}
+
+// Achievement State (internal)
+export interface Achievement extends AchievementDefinition {
+  isUnlocked: boolean;
+  unlockedAt?: string;
+  progress: number;
+}
+
+// Level Definition (provided by app)
+export interface LevelDefinition {
+  level: number;
+  minPoints: number;
+  maxPoints: number;
+}
+
+// Level State (internal)
+export interface LevelState {
+  currentLevel: number;
+  currentPoints: number;
+  pointsToNext: number;
+  progress: number;
+}
+
+// Streak State
+export interface StreakState {
+  current: number;
+  longest: number;
+  lastActivityDate: string | null;
+}
+
+// Gamification Config (provided by app via props)
+export interface GamificationConfig {
+  storageKey: string;
+  achievements: AchievementDefinition[];
+  levels: LevelDefinition[];
+  pointsPerAction?: number;
+  streakBonusMultiplier?: number;
+}
+
+// Store State
+export interface GamificationState {
+  points: number;
+  totalTasksCompleted: number;
+  achievements: Achievement[];
+  streak: StreakState;
+  isLoading: boolean;
+  isInitialized: boolean;
+}
+
+// Store Actions
+export interface GamificationActions {
+  initialize: (config: GamificationConfig) => Promise<void>;
+  addPoints: (amount: number) => void;
+  completeTask: () => void;
+  updateStreak: () => void;
+  checkAchievements: () => Achievement[];
+  reset: () => Promise<void>;
+}
+
+// Combined Store
+export type GamificationStore = GamificationState & GamificationActions;
+
+// UI Component Props (all text via props - NO hardcoded strings)
+export interface LevelProgressProps {
+  level: number;
+  points: number;
+  levelTitle: string;
+  pointsToNext: number;
+  progress: number;
+  showPoints?: boolean;
+}
+
+export interface AchievementCardProps {
+  title: string;
+  description: string;
+  icon: string;
+  isUnlocked: boolean;
+  progress: number;
+  threshold: number;
+}
+
+export interface StreakDisplayProps {
+  current: number;
+  longest: number;
+  streakLabel: string;
+  bestLabel: string;
+}
+
+export interface PointsBadgeProps {
+  points: number;
+  label?: string;
+}

package/src/domains/gamification/types/settings.ts

@@ -0,0 +1,28 @@
+/**
+ * Gamification Settings Integration Types
+ * Wrapper types for integrating gamification into settings
+ */
+
+import type { GamificationConfig } from "./index";
+import type { GamificationScreenProps } from "../components/GamificationScreen/types";
+
+/**
+ * Configuration for gamification in settings
+ */
+export interface GamificationSettingsConfig {
+  enabled: boolean;
+  config: GamificationConfig;
+  screenProps: Omit<GamificationScreenProps, "levelProps" | "stats" | "achievements">;
+  onNavigate?: () => void;
+}
+
+/**
+ * Configuration for gamification menu item
+ */
+export interface GamificationMenuConfig {
+  enabled: boolean;
+  title: string;
+  subtitle?: string;
+  icon?: string;
+  onPress?: () => void;
+}

package/src/domains/gamification/utils/calculations.ts

@@ -0,0 +1,85 @@
+/**
+ * Gamification Calculations
+ * Pure utility functions - NO side effects
+ */
+
+import type { LevelDefinition, LevelState, Achievement, AchievementDefinition } from "../types";
+
+export const calculateLevel = (
+  points: number,
+  levels: LevelDefinition[]
+): LevelState => {
+  const sortedLevels = [...levels].sort((a, b) => a.minPoints - b.minPoints);
+
+  let currentLevelDef = sortedLevels[0];
+  let nextLevelDef: LevelDefinition | null = null;
+
+  for (let i = 0; i < sortedLevels.length; i++) {
+    if (points >= sortedLevels[i].minPoints) {
+      currentLevelDef = sortedLevels[i];
+      nextLevelDef = sortedLevels[i + 1] || null;
+    }
+  }
+
+  const pointsInLevel = points - currentLevelDef.minPoints;
+  const levelRange = nextLevelDef
+    ? nextLevelDef.minPoints - currentLevelDef.minPoints
+    : 100;
+  const progress = Math.min(100, (pointsInLevel / levelRange) * 100);
+  const pointsToNext = nextLevelDef
+    ? nextLevelDef.minPoints - points
+    : 0;
+
+  return {
+    currentLevel: currentLevelDef.level,
+    currentPoints: points,
+    pointsToNext,
+    progress,
+  };
+};
+
+export const checkAchievementUnlock = (
+  definition: AchievementDefinition,
+  tasksCompleted: number,
+  currentStreak: number
+): boolean => {
+  switch (definition.type) {
+    case "count":
+      return tasksCompleted >= definition.threshold;
+    case "streak":
+      return currentStreak >= definition.threshold;
+    case "milestone":
+      return tasksCompleted >= definition.threshold;
+    default:
+      return false;
+  }
+};
+
+export const updateAchievementProgress = (
+  definition: AchievementDefinition,
+  tasksCompleted: number,
+  currentStreak: number
+): number => {
+  const value = definition.type === "streak" ? currentStreak : tasksCompleted;
+  return Math.min(100, (value / definition.threshold) * 100);
+};
+
+export const isStreakActive = (lastActivityDate: string | null): boolean => {
+  if (!lastActivityDate) return false;
+
+  const last = new Date(lastActivityDate);
+  const now = new Date();
+  const diffDays = Math.floor(
+    (now.getTime() - last.getTime()) / (1000 * 60 * 60 * 24)
+  );
+
+  return diffDays <= 1;
+};
+
+export const isSameDay = (date1: Date, date2: Date): boolean => {
+  return (
+    date1.getFullYear() === date2.getFullYear() &&
+    date1.getMonth() === date2.getMonth() &&
+    date1.getDate() === date2.getDate()
+  );
+};

package/src/index.ts

@@ -120,14 +120,24 @@ export * from "./domains/cloud-sync";
 // Dev Domain - Development-only settings (DEV mode)
 export * from "./domains/dev";
 
+// Gamification Domain - Achievements, levels, streaks
+export * from "./domains/gamification";
+
+
 // =============================================================================
-// PRESENTATION LAYER - Re-exports from Dependencies
+// PRESENTATION LAYER - Config Creator Utilities
 // =============================================================================
 
-// @ts-ignore - Re-exporting from peer dependency
-export { OnboardingResetSetting } from '@umituz/react-native-onboarding';
-// @ts-ignore - Re-exporting from peer dependency  
-export type { OnboardingResetSettingProps } from '@umituz/react-native-onboarding';
-
-// @ts-ignore - Re-exporting from peer dependency
-// @ts-ignore - Re-exporting from peer dependency
+export {
+  createAppearanceConfig,
+  createLanguageConfig,
+  createNotificationsConfig,
+  createAboutConfig,
+  createLegalConfig,
+  createFeedbackConfig,
+  createRatingConfig,
+  createFAQConfig,
+  createSubscriptionConfig,
+  type TranslationFunction,
+  type FeedbackFormData,
+} from './presentation/utils';

package/src/presentation/navigation/SettingsStackNavigator.tsx

@@ -29,8 +29,10 @@ import {
   createNotificationsScreenOptions,
   createFAQScreenOptions,
   createLanguageSelectionScreenOptions,
+  createGamificationScreenOptions,
 } from "./utils";
 import type { SettingsStackParamList, SettingsStackNavigatorProps } from "./types";
+import { GamificationScreenWrapper } from "../../domains/gamification";
 
 const Stack = createStackNavigator<SettingsStackParamList>();
 
@@ -45,6 +47,7 @@ export const SettingsStackNavigator: React.FC<SettingsStackNavigatorProps> = ({
   devSettings,
   customSections = [],
   showHeader = true,
+  gamificationConfig,
 }) => {
   const tokens = useAppDesignTokens();
   const { t } = useLocalization();
@@ -143,6 +146,15 @@ export const SettingsStackNavigator: React.FC<SettingsStackNavigatorProps> = ({
         ) : null
       )}
 
+      {gamificationConfig?.enabled && (
+        <Stack.Screen
+          name="Gamification"
+          options={createGamificationScreenOptions(t)}
+        >
+          {() => <GamificationScreenWrapper config={gamificationConfig} />}
+        </Stack.Screen>
+      )}
+
       <Stack.Screen
         name="LanguageSelection"
         options={createLanguageSelectionScreenOptions(t)}

package/src/presentation/navigation/types.ts

@@ -42,6 +42,7 @@ export type SettingsStackParamList = {
   Notifications: undefined;
   FAQ: undefined;
   LanguageSelection: undefined;
+  Gamification: undefined;
 };
 
 /**
@@ -89,4 +90,5 @@ export interface SettingsStackNavigatorProps {
   devSettings?: DevSettingsProps;
   customSections?: CustomSettingsSection[];
   showHeader?: boolean;
+  gamificationConfig?: import("../../domains/gamification").GamificationSettingsConfig;
 }

package/src/presentation/navigation/utils/navigationScreenOptions.ts

@@ -54,3 +54,10 @@ export const createLanguageSelectionScreenOptions = (t: any) => ({
   headerTitle: t("settings.language.title"),
   headerTitleAlign: "center" as const,
 });
+
+export const createGamificationScreenOptions = (t: any) => ({
+  headerShown: true,
+  headerTitle: t("settings.gamification.title"),
+  headerTitleAlign: "center" as const,
+});
+

package/src/presentation/screens/types/UserFeatureConfig.ts

@@ -12,6 +12,8 @@ import type { FeedbackType } from "../../../domains/feedback/domain/entities/Fee
 export interface UserProfileConfig {
   /** Show user profile header */
   enabled?: boolean;
+  /** Custom section title for grouping */
+  sectionTitle?: string;
   /** Custom display name for anonymous users */
   anonymousDisplayName?: string;
   /** Custom avatar service URL */