react-achievements 3.0.2 → 3.2.0

package/dist/index.js

@@ -99,6 +99,29 @@ class LocalStorage {
     }
 }
 
+class MemoryStorage {
+    constructor() {
+        this.metrics = {};
+        this.unlockedAchievements = [];
+    }
+    getMetrics() {
+        return this.metrics;
+    }
+    setMetrics(metrics) {
+        this.metrics = metrics;
+    }
+    getUnlockedAchievements() {
+        return this.unlockedAchievements;
+    }
+    setUnlockedAchievements(achievements) {
+        this.unlockedAchievements = achievements;
+    }
+    clear() {
+        this.metrics = {};
+        this.unlockedAchievements = [];
+    }
+}
+
 const getPositionStyles = (position) => {
     const base = {
         position: 'fixed',
@@ -129,94 +152,14 @@ const BadgesButton = ({ onClick, position, styles = {}, unlockedAchievements })
 };
 
 const defaultAchievementIcons = {
-    // General Progress & Milestones
-    levelUp: '🏆',
-    questComplete: '📜',
-    monsterDefeated: '⚔️',
-    itemCollected: '📦',
-    challengeCompleted: '🏁',
-    milestoneReached: '🏅',
-    firstStep: '👣',
-    newBeginnings: '🌱',
-    breakthrough: '💡',
-    growth: '📈',
-    // Social & Engagement
-    shared: '🔗',
-    liked: '❤️',
-    commented: '💬',
-    followed: '👥',
-    invited: '🤝',
-    communityMember: '🏘️',
-    supporter: '🌟',
-    connected: '🌐',
-    participant: '🙋',
-    influencer: '📣',
-    // Time & Activity
-    activeDay: '☀️',
-    activeWeek: '📅',
-    activeMonth: '🗓️',
-    earlyBird: '⏰',
-    nightOwl: '🌙',
-    streak: '🔥',
-    dedicated: '⏳',
-    punctual: '⏱️',
-    consistent: '🔄',
-    marathon: '🏃',
-    // Creativity & Skill
-    artist: '🎨',
-    writer: '✍️',
-    innovator: '🔬',
-    creator: '🛠️',
-    expert: '🎓',
-    master: '👑',
-    pioneer: '🚀',
-    performer: '🎭',
-    thinker: '🧠',
-    explorer: '🗺️',
-    // Achievement Types
-    bronze: '🥉',
-    silver: '🥈',
-    gold: '🥇',
-    diamond: '💎',
-    legendary: '✨',
-    epic: '💥',
-    rare: '🔮',
-    common: '🔘',
-    special: '🎁',
-    hidden: '❓',
-    // Numbers & Counters
-    one: '1️⃣',
-    ten: '🔟',
-    hundred: '💯',
-    thousand: '🔢',
-    // Actions & Interactions
-    clicked: '🖱️',
-    used: '🔑',
-    found: '🔍',
-    built: '🧱',
-    solved: '🧩',
-    discovered: '🔭',
-    unlocked: '🔓',
-    upgraded: '⬆️',
-    repaired: '🔧',
-    defended: '🛡️',
-    // Placeholders
-    default: '⭐', // A fallback icon
-    loading: '⏳',
-    error: '⚠️',
-    success: '✅',
-    failure: '❌',
-    // Miscellaneous
+    // Essential fallback icons for system use
+    default: '⭐', // Fallback when no icon is provided
+    loading: '⏳', // For loading states
+    error: '⚠️', // For error states
+    success: '✅', // For success states
+    // A few common icons for backward compatibility
     trophy: '🏆',
     star: '⭐',
-    flag: '🚩',
-    puzzle: '🧩',
-    gem: '💎',
-    crown: '👑',
-    medal: '🏅',
-    ribbon: '🎗️',
-    badge: '🎖️',
-    shield: '🛡️',
 };
 
 const BadgesModal = ({ isOpen, onClose, achievements, styles = {}, icons = {} }) => {
@@ -316,31 +259,100 @@ const ConfettiWrapper = ({ show }) => {
         } }));
 };
 
-class MemoryStorage {
-    constructor() {
-        this.metrics = {};
-        this.unlockedAchievements = [];
-    }
-    getMetrics() {
-        return this.metrics;
-    }
-    setMetrics(metrics) {
-        this.metrics = metrics;
-    }
-    getUnlockedAchievements() {
-        return this.unlockedAchievements;
-    }
-    setUnlockedAchievements(achievements) {
-        this.unlockedAchievements = achievements;
-    }
-    clear() {
-        this.metrics = {};
-        this.unlockedAchievements = [];
+// Type guard to check if config is simple format
+function isSimpleConfig(config) {
+    if (!config || typeof config !== 'object')
+        return false;
+    const firstKey = Object.keys(config)[0];
+    if (!firstKey)
+        return true; // Empty config is considered simple
+    const firstValue = config[firstKey];
+    // Check if it's the current complex format (array of AchievementCondition)
+    if (Array.isArray(firstValue))
+        return false;
+    // Check if it's the simple format (object with string keys)
+    return typeof firstValue === 'object' && !Array.isArray(firstValue);
+}
+// Generate a unique ID for achievements
+function generateId() {
+    return Math.random().toString(36).substr(2, 9);
+}
+// Check if achievement details has a custom condition
+function hasCustomCondition(details) {
+    return 'condition' in details && typeof details.condition === 'function';
+}
+// Convert simple config to complex config format
+function normalizeAchievements(config) {
+    if (!isSimpleConfig(config)) {
+        // Already in complex format, return as-is
+        return config;
     }
+    const normalized = {};
+    Object.entries(config).forEach(([metric, achievements]) => {
+        normalized[metric] = Object.entries(achievements).map(([key, achievement]) => {
+            if (hasCustomCondition(achievement)) {
+                // Custom condition function
+                return {
+                    isConditionMet: (value, state) => {
+                        // Convert internal metrics format (arrays) to simple format for custom conditions
+                        const simpleMetrics = {};
+                        Object.entries(state.metrics).forEach(([key, val]) => {
+                            simpleMetrics[key] = Array.isArray(val) ? val[0] : val;
+                        });
+                        return achievement.condition(simpleMetrics);
+                    },
+                    achievementDetails: {
+                        achievementId: `${metric}_custom_${generateId()}`,
+                        achievementTitle: achievement.title,
+                        achievementDescription: achievement.description || '',
+                        achievementIconKey: achievement.icon || 'default'
+                    }
+                };
+            }
+            else {
+                // Threshold-based achievement
+                const threshold = parseFloat(key);
+                const isValidThreshold = !isNaN(threshold);
+                let conditionMet;
+                if (isValidThreshold) {
+                    // Numeric threshold
+                    conditionMet = (value) => {
+                        const numValue = Array.isArray(value) ? value[0] : value;
+                        return typeof numValue === 'number' && numValue >= threshold;
+                    };
+                }
+                else {
+                    // String or boolean threshold
+                    conditionMet = (value) => {
+                        const actualValue = Array.isArray(value) ? value[0] : value;
+                        // Handle boolean thresholds
+                        if (key === 'true')
+                            return actualValue === true;
+                        if (key === 'false')
+                            return actualValue === false;
+                        // Handle string thresholds
+                        return actualValue === key;
+                    };
+                }
+                return {
+                    isConditionMet: conditionMet,
+                    achievementDetails: {
+                        achievementId: `${metric}_${key}`,
+                        achievementTitle: achievement.title,
+                        achievementDescription: achievement.description || (isValidThreshold ? `Reach ${threshold} ${metric}` : `Achieve ${key} for ${metric}`),
+                        achievementIconKey: achievement.icon || 'default'
+                    }
+                };
+            }
+        });
+    });
+    return normalized;
 }
 
 const AchievementContext = createContext(undefined);
-const AchievementProvider = ({ achievements, storage = StorageType.Local, children, icons = {}, }) => {
+const AchievementProvider = ({ achievements: achievementsConfig, storage = StorageType.Local, children, icons = {}, }) => {
+    // Normalize the configuration to the complex format
+    const achievements = normalizeAchievements(achievementsConfig);
     const [achievementState, setAchievementState] = useState({
         unlocked: [],
         all: achievements,
@@ -432,12 +444,16 @@ const AchievementProvider = ({ achievements, storage = StorageType.Local, childr
         let newlyUnlockedAchievements = [];
         let achievementToShow = null;
         Object.entries(achievements).forEach(([metricName, metricAchievements]) => {
-            const currentValue = metrics[metricName];
-            if (currentValue !== undefined) {
-                metricAchievements.forEach((achievement) => {
-                    const state = { metrics, unlockedAchievements: achievementState.unlocked };
+            metricAchievements.forEach((achievement) => {
+                const state = { metrics, unlockedAchievements: achievementState.unlocked };
+                const achievementId = achievement.achievementDetails.achievementId;
+                // For custom conditions, we always check against all metrics
+                // For threshold-based conditions, we check against the specific metric
+                const currentValue = metrics[metricName];
+                const shouldCheckAchievement = currentValue !== undefined ||
+                    achievement.achievementDetails.achievementId.includes('_custom_');
+                if (shouldCheckAchievement) {
                     const valueToCheck = currentValue;
-                    const achievementId = achievement.achievementDetails.achievementId;
                     if (achievement.isConditionMet(valueToCheck, state)) {
                         if (!achievementState.unlocked.includes(achievementId) &&
                             !newlyUnlockedAchievements.includes(achievementId)) {
@@ -447,8 +463,8 @@ const AchievementProvider = ({ achievements, storage = StorageType.Local, childr
                             }
                         }
                     }
-                });
-            }
+                }
+            });
         });
         if (newlyUnlockedAchievements.length > 0) {
             const allUnlocked = [...achievementState.unlocked, ...newlyUnlockedAchievements];
@@ -550,6 +566,47 @@ const useAchievements = () => {
     return context;
 };
 
+/**
+ * A simplified hook for achievement tracking.
+ * Provides an easier API for common use cases while maintaining access to advanced features.
+ */
+const useSimpleAchievements = () => {
+    const { update, achievements, reset, getState } = useAchievements();
+    return {
+        /**
+         * Track a metric value for achievements
+         * @param metric - The metric name (e.g., 'score', 'level')
+         * @param value - The metric value
+         */
+        track: (metric, value) => update({ [metric]: value }),
+        /**
+         * Track multiple metrics at once
+         * @param metrics - Object with metric names as keys and values
+         */
+        trackMultiple: (metrics) => update(metrics),
+        /**
+         * Array of unlocked achievement IDs
+         */
+        unlocked: achievements.unlocked,
+        /**
+         * All available achievements
+         */
+        all: achievements.all,
+        /**
+         * Number of unlocked achievements
+         */
+        unlockedCount: achievements.unlocked.length,
+        /**
+         * Reset all achievement progress
+         */
+        reset,
+        /**
+         * Get current state (advanced usage)
+         */
+        getState,
+    };
+};
+
 const defaultStyles = {
     badgesButton: {
         backgroundColor: '#4CAF50',
@@ -627,5 +684,291 @@ const defaultStyles = {
     },
 };
 
-export { AchievementContext, AchievementProvider, BadgesButton, BadgesModal, ConfettiWrapper, LocalStorage, StorageType, defaultAchievementIcons, defaultStyles, useAchievements };
+/**
+ * Base class for chainable achievement configuration (Tier 2)
+ */
+class Achievement {
+    constructor(metric, defaultAward) {
+        this.metric = metric;
+        this.award = defaultAward;
+    }
+    /**
+     * Customize the award details for this achievement
+     * @param award - Custom award details
+     * @returns This achievement for chaining
+     */
+    withAward(award) {
+        this.award = Object.assign(Object.assign({}, this.award), award);
+        return this;
+    }
+}
+/**
+ * Threshold-based achievement (score, level, etc.)
+ */
+class ThresholdAchievement extends Achievement {
+    constructor(metric, threshold, defaultAward) {
+        super(metric, defaultAward);
+        this.threshold = threshold;
+    }
+    toConfig() {
+        return {
+            [this.metric]: {
+                [this.threshold]: {
+                    title: this.award.title,
+                    description: this.award.description,
+                    icon: this.award.icon
+                }
+            }
+        };
+    }
+}
+/**
+ * Boolean achievement (tutorial completion, first login, etc.)
+ */
+class BooleanAchievement extends Achievement {
+    toConfig() {
+        return {
+            [this.metric]: {
+                true: {
+                    title: this.award.title,
+                    description: this.award.description,
+                    icon: this.award.icon
+                }
+            }
+        };
+    }
+}
+/**
+ * Value-based achievement (character class, difficulty, etc.)
+ */
+class ValueAchievement extends Achievement {
+    constructor(metric, value, defaultAward) {
+        super(metric, defaultAward);
+        this.value = value;
+    }
+    toConfig() {
+        return {
+            [this.metric]: {
+                [this.value]: {
+                    title: this.award.title,
+                    description: this.award.description,
+                    icon: this.award.icon
+                }
+            }
+        };
+    }
+}
+/**
+ * Complex achievement builder for power users (Tier 3)
+ */
+class ComplexAchievementBuilder {
+    constructor() {
+        this.id = '';
+        this.metric = '';
+        this.condition = null;
+        this.award = {};
+    }
+    /**
+     * Set the unique identifier for this achievement
+     */
+    withId(id) {
+        this.id = id;
+        return this;
+    }
+    /**
+     * Set the metric this achievement tracks
+     */
+    withMetric(metric) {
+        this.metric = metric;
+        return this;
+    }
+    /**
+     * Set the condition function that determines if achievement is unlocked
+     */
+    withCondition(fn) {
+        this.condition = fn;
+        return this;
+    }
+    /**
+     * Set the award details for this achievement
+     */
+    withAward(award) {
+        this.award = Object.assign(Object.assign({}, this.award), award);
+        return this;
+    }
+    /**
+     * Build the final achievement configuration
+     */
+    build() {
+        if (!this.id || !this.metric || !this.condition) {
+            throw new Error('Complex achievement requires id, metric, and condition');
+        }
+        // Convert our two-parameter condition function to the single-parameter format
+        // expected by the existing CustomAchievementDetails type
+        const compatibleCondition = (metrics) => {
+            const state = {
+                metrics: {}, // We don't have access to the full metrics structure here
+                unlockedAchievements: []
+            };
+            return this.condition(metrics[this.metric], state);
+        };
+        return {
+            [this.id]: {
+                custom: {
+                    title: this.award.title || this.id,
+                    description: this.award.description || `Achieve ${this.award.title || this.id}`,
+                    icon: this.award.icon || '💎',
+                    condition: compatibleCondition
+                }
+            }
+        };
+    }
+}
+/**
+ * Main AchievementBuilder with three-tier API
+ * Tier 1: Simple static methods with smart defaults
+ * Tier 2: Chainable customization
+ * Tier 3: Full builder for complex logic
+ */
+class AchievementBuilder {
+    // TIER 1: Simple Static Methods (90% of use cases)
+    /**
+     * Create a single score achievement with smart defaults
+     * @param threshold - Score threshold to achieve
+     * @returns Chainable ThresholdAchievement
+     */
+    static createScoreAchievement(threshold) {
+        return new ThresholdAchievement('score', threshold, {
+            title: `Score ${threshold}!`,
+            description: `Score ${threshold} points`,
+            icon: '🏆'
+        });
+    }
+    /**
+     * Create multiple score achievements
+     * @param thresholds - Array of thresholds or [threshold, award] tuples
+     * @returns Complete SimpleAchievementConfig
+     */
+    static createScoreAchievements(thresholds) {
+        const config = { score: {} };
+        thresholds.forEach(item => {
+            if (typeof item === 'number') {
+                // Use default award
+                config.score[item] = {
+                    title: `Score ${item}!`,
+                    description: `Score ${item} points`,
+                    icon: '🏆'
+                };
+            }
+            else {
+                // Custom award
+                const [threshold, award] = item;
+                config.score[threshold] = {
+                    title: award.title || `Score ${threshold}!`,
+                    description: award.description || `Score ${threshold} points`,
+                    icon: award.icon || '🏆'
+                };
+            }
+        });
+        return config;
+    }
+    /**
+     * Create a single level achievement with smart defaults
+     * @param level - Level threshold to achieve
+     * @returns Chainable ThresholdAchievement
+     */
+    static createLevelAchievement(level) {
+        return new ThresholdAchievement('level', level, {
+            title: `Level ${level}!`,
+            description: `Reach level ${level}`,
+            icon: '📈'
+        });
+    }
+    /**
+     * Create multiple level achievements
+     * @param levels - Array of levels or [level, award] tuples
+     * @returns Complete SimpleAchievementConfig
+     */
+    static createLevelAchievements(levels) {
+        const config = { level: {} };
+        levels.forEach(item => {
+            if (typeof item === 'number') {
+                // Use default award
+                config.level[item] = {
+                    title: `Level ${item}!`,
+                    description: `Reach level ${item}`,
+                    icon: '📈'
+                };
+            }
+            else {
+                // Custom award
+                const [level, award] = item;
+                config.level[level] = {
+                    title: award.title || `Level ${level}!`,
+                    description: award.description || `Reach level ${level}`,
+                    icon: award.icon || '📈'
+                };
+            }
+        });
+        return config;
+    }
+    /**
+     * Create a boolean achievement with smart defaults
+     * @param metric - The metric name (e.g., 'completedTutorial')
+     * @returns Chainable BooleanAchievement
+     */
+    static createBooleanAchievement(metric) {
+        // Convert camelCase to Title Case
+        const formattedMetric = metric.replace(/([A-Z])/g, ' $1').toLowerCase();
+        const titleCase = formattedMetric.charAt(0).toUpperCase() + formattedMetric.slice(1);
+        return new BooleanAchievement(metric, {
+            title: `${titleCase}!`,
+            description: `Complete ${formattedMetric}`,
+            icon: '✅'
+        });
+    }
+    /**
+     * Create a value-based achievement with smart defaults
+     * @param metric - The metric name (e.g., 'characterClass')
+     * @param value - The value to match (e.g., 'wizard')
+     * @returns Chainable ValueAchievement
+     */
+    static createValueAchievement(metric, value) {
+        const formattedValue = value.charAt(0).toUpperCase() + value.slice(1);
+        return new ValueAchievement(metric, value, {
+            title: `${formattedValue}!`,
+            description: `Choose ${formattedValue.toLowerCase()} for ${metric}`,
+            icon: '🎯'
+        });
+    }
+    // TIER 3: Full Builder for Complex Logic
+    /**
+     * Create a complex achievement builder for power users
+     * @returns ComplexAchievementBuilder for full control
+     */
+    static create() {
+        return new ComplexAchievementBuilder();
+    }
+    // UTILITY METHODS
+    /**
+     * Combine multiple achievement configurations
+     * @param achievements - Array of SimpleAchievementConfig objects or Achievement instances
+     * @returns Combined SimpleAchievementConfig
+     */
+    static combine(achievements) {
+        const combined = {};
+        achievements.forEach(achievement => {
+            const config = achievement instanceof Achievement ? achievement.toConfig() : achievement;
+            Object.keys(config).forEach(key => {
+                if (!combined[key]) {
+                    combined[key] = {};
+                }
+                Object.assign(combined[key], config[key]);
+            });
+        });
+        return combined;
+    }
+}
+
+export { AchievementBuilder, AchievementContext, AchievementProvider, BadgesButton, BadgesModal, ConfettiWrapper, LocalStorage, MemoryStorage, StorageType, defaultAchievementIcons, defaultStyles, isSimpleConfig, normalizeAchievements, useAchievements, useSimpleAchievements };
 //# sourceMappingURL=index.js.map