@umituz/react-native-settings 4.20.62 → 4.21.1

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

@@ -0,0 +1,13 @@
+/**
+ * Gamification Components
+ * All text via props - NO hardcoded strings
+ */
+
+export { LevelProgress, type LevelProgressProps } from "./LevelProgress";
+export { PointsBadge, type PointsBadgeProps } from "./PointsBadge";
+export { AchievementCard, type AchievementCardProps } from "./AchievementCard";
+export { AchievementToast, type AchievementToastProps } from "./AchievementToast";
+export { StreakDisplay, type StreakDisplayProps } from "./StreakDisplay";
+export { StatsCard, type StatsCardProps } from "./StatsCard";
+export { AchievementItem, type AchievementItemProps } from "./AchievementItem";
+export { GamificationScreen, type GamificationScreenProps } from "./GamificationScreen/index";

package/src/domains/gamification/examples/gamification.config.example.ts

@@ -5,7 +5,7 @@
  * src/domains/settings/config/gamification.config.ts
  */
 
-import type { GamificationSettingsConfig } from "../types";
+import type { GamificationSettingsConfig } from "../types/settings";
 
 /**
  * Creates gamification configuration for settings

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

@@ -1,38 +1,65 @@
 /**
- * Gamification Domain - Public API
+ * @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";
+} from "./types/settings";
 
-// Components
-export { GamificationScreenWrapper } from "./components/GamificationScreenWrapper";
-export type { GamificationScreenWrapperProps } from "./components/GamificationScreenWrapper";
+// Store
+export { useGamificationStore } from "./store/gamificationStore";
 
-export { GamificationSettingsItem } from "./components/GamificationSettingsItem";
-export type { GamificationSettingsItemProps } from "./components/GamificationSettingsItem";
+// Hooks
+export { useGamification, type UseGamificationReturn } from "./hooks/useGamification";
 
-// Re-export from gamification package for convenience
+// Utils
+export {
+  calculateLevel,
+  checkAchievementUnlock,
+  updateAchievementProgress,
+  isStreakActive,
+  isSameDay,
+} from "./utils/calculations";
+
+// Components
 export {
-  useGamification,
-  useGamificationStore,
   LevelProgress,
+  type LevelProgressProps,
   PointsBadge,
+  type PointsBadgeProps,
   AchievementCard,
+  type AchievementCardProps,
   AchievementToast,
+  type AchievementToastProps,
   StreakDisplay,
+  type StreakDisplayProps,
   StatsCard,
+  type StatsCardProps,
   AchievementItem,
-} from "@umituz/react-native-gamification";
+  type AchievementItemProps,
+  GamificationScreen,
+  type GamificationScreenProps,
+} from "./components";
 
-export type {
-  GamificationConfig,
-  GamificationState,
-  Achievement,
-  LevelState,
-  StreakState,
-  UseGamificationReturn,
-} from "@umituz/react-native-gamification";
+// 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

@@ -1,31 +1,103 @@
 /**
- * Gamification Domain - Types
- * Settings package integration for gamification
+ * Gamification Types
+ * Generic types for 100+ apps - NO app-specific code
  */
 
-import type {
-  GamificationConfig,
-  GamificationScreenProps,
-} from "@umituz/react-native-gamification";
+// Achievement Definition (provided by app)
+export interface AchievementDefinition {
+  id: string;
+  threshold: number;
+  type: "count" | "streak" | "milestone";
+}
 
-/**
- * Gamification settings configuration
- * Passed from app to settings package
- */
-export interface GamificationSettingsConfig {
-  enabled: boolean;
-  config: GamificationConfig;
-  screenProps: Omit<GamificationScreenProps, "levelProps" | "stats" | "achievements">;
-  onNavigate?: () => void;
+// Achievement State (internal)
+export interface Achievement extends AchievementDefinition {
+  isUnlocked: boolean;
+  unlockedAt?: string;
+  progress: number;
 }
 
-/**
- * Gamification menu item configuration
- */
-export interface GamificationMenuConfig {
-  enabled: boolean;
+// 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;
-  subtitle?: string;
-  icon?: string;
-  onPress?: () => void;
+  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/.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,51 +0,0 @@
----
-name: Bug report
-about: Create a report to help us improve
-title: '[BUG] '
-labels: bug
-assignees: ''
----
-
-## Bug Description
-
-A clear and concise description of what the bug is.
-
-## Reproduction Steps
-
-1. Go to '...'
-2. Click on '....'
-3. Scroll down to '....'
-4. See error
-
-## Expected Behavior
-
-A clear and concise description of what you expected to happen.
-
-## Actual Behavior
-
-A clear and concise description of what actually happened.
-
-## Screenshots
-
-If applicable, add screenshots to help explain your problem.
-
-## Environment
-
-| Software | Version |
-|----------|---------|
-| React Native | |
-| iOS | |
-| Android | |
-| @umituz/react-native-settings | |
-| Node | |
-| npm/yarn | |
-
-## Additional Context
-
-Add any other context about the problem here.
-
-## Console Logs
-
-```
-Paste your console logs here
-```

package/.github/ISSUE_TEMPLATE/documentation.md

@@ -1,52 +0,0 @@
----
-name: Documentation
-about: Report documentation issues or suggest improvements
-title: '[DOCS] '
-labels: documentation
-assignees: ''
----
-
-## Documentation Issue
-
-Please describe the documentation issue:
-
-- [ ] Inaccurate information
-- [ ] Missing information
-- [ ] Unclear or confusing
-- [ ] Outdated content
-- [ ] Typo or grammatical error
-- [ ] Suggestion for improvement
-
-## Affected Documentation
-
-Which documentation file(s) are affected?
-- [ ] README.md
-- [ ] ARCHITECTURE.md
-- [ ] TESTING.md
-- [ ] AI_AGENT_GUIDELINES.md
-- [ ] SETTINGS_SCREEN_GUIDE.md
-- [ ] Specific component README
-- [ ] Other (please specify)
-
-## Current Documentation
-
-Paste or describe the current documentation content that needs improvement:
-
-```
-Paste current documentation here
-```
-
-## Suggested Change
-
-Please describe what should be changed or added:
-
-## Additional Context
-
-Add any other context, screenshots, or examples about the documentation issue.
-
-## AI Agent Guidelines
-
-If this is about AI agent guidelines, please specify:
-- Which file needs updating
-- What guidelines are missing or unclear
-- How the guidelines could be improved