react-achievements 3.1.0 → 3.2.0

package/dist/index.d.ts

@@ -104,6 +104,17 @@ declare class LocalStorage implements AchievementStorage {
     clear(): void;
 }
 
+declare class MemoryStorage implements AchievementStorage {
+    private metrics;
+    private unlockedAchievements;
+    constructor();
+    getMetrics(): AchievementMetrics;
+    setMetrics(metrics: AchievementMetrics): void;
+    getUnlockedAchievements(): string[];
+    setUnlockedAchievements(achievements: string[]): void;
+    clear(): void;
+}
+
 interface BadgesButtonProps {
     onClick: () => void;
     position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
@@ -193,88 +204,149 @@ declare const useSimpleAchievements: () => {
 declare const defaultStyles: Required<StylesProps>;
 
 declare const defaultAchievementIcons: {
-    levelUp: string;
-    questComplete: string;
-    monsterDefeated: string;
-    itemCollected: string;
-    challengeCompleted: string;
-    milestoneReached: string;
-    firstStep: string;
-    newBeginnings: string;
-    breakthrough: string;
-    growth: string;
-    shared: string;
-    liked: string;
-    commented: string;
-    followed: string;
-    invited: string;
-    communityMember: string;
-    supporter: string;
-    connected: string;
-    participant: string;
-    influencer: string;
-    activeDay: string;
-    activeWeek: string;
-    activeMonth: string;
-    earlyBird: string;
-    nightOwl: string;
-    streak: string;
-    dedicated: string;
-    punctual: string;
-    consistent: string;
-    marathon: string;
-    artist: string;
-    writer: string;
-    innovator: string;
-    creator: string;
-    expert: string;
-    master: string;
-    pioneer: string;
-    performer: string;
-    thinker: string;
-    explorer: string;
-    bronze: string;
-    silver: string;
-    gold: string;
-    diamond: string;
-    legendary: string;
-    epic: string;
-    rare: string;
-    common: string;
-    special: string;
-    hidden: string;
-    one: string;
-    ten: string;
-    hundred: string;
-    thousand: string;
-    clicked: string;
-    used: string;
-    found: string;
-    built: string;
-    solved: string;
-    discovered: string;
-    unlocked: string;
-    upgraded: string;
-    repaired: string;
-    defended: string;
     default: string;
     loading: string;
     error: string;
     success: string;
-    failure: string;
     trophy: string;
     star: string;
-    flag: string;
-    puzzle: string;
-    gem: string;
-    crown: string;
-    medal: string;
-    ribbon: string;
-    badge: string;
-    shield: string;
 };
 
 declare function isSimpleConfig(config: AchievementConfigurationType): config is SimpleAchievementConfig;
 declare function normalizeAchievements(config: AchievementConfigurationType): AchievementConfiguration;
 
-export { AchievementCondition, AchievementConfiguration, AchievementConfigurationType, AchievementContext, AchievementContextValue, AchievementDetails, AchievementMetricArrayValue, AchievementMetricValue, AchievementMetrics, AchievementProvider, AchievementProviderProps$1 as AchievementProviderProps, AchievementState, AchievementStorage, BadgesButton, BadgesModal, ConfettiWrapper, CustomAchievementDetails, InitialAchievementMetrics, LocalStorage, SimpleAchievementConfig, SimpleAchievementDetails, StorageType, StylesProps, defaultAchievementIcons, defaultStyles, isSimpleConfig, normalizeAchievements, useAchievements, useSimpleAchievements };
+/**
+ * Helper interface for cleaner achievement award definitions
+ */
+interface AwardDetails {
+    title?: string;
+    description?: string;
+    icon?: string;
+}
+/**
+ * Base class for chainable achievement configuration (Tier 2)
+ */
+declare abstract class Achievement {
+    protected metric: string;
+    protected award: AwardDetails;
+    constructor(metric: string, defaultAward: AwardDetails);
+    /**
+     * Customize the award details for this achievement
+     * @param award - Custom award details
+     * @returns This achievement for chaining
+     */
+    withAward(award: AwardDetails): Achievement;
+    /**
+     * Convert this achievement to a SimpleAchievementConfig
+     */
+    abstract toConfig(): SimpleAchievementConfig;
+}
+/**
+ * Threshold-based achievement (score, level, etc.)
+ */
+declare class ThresholdAchievement extends Achievement {
+    private threshold;
+    constructor(metric: string, threshold: number, defaultAward: AwardDetails);
+    toConfig(): SimpleAchievementConfig;
+}
+/**
+ * Boolean achievement (tutorial completion, first login, etc.)
+ */
+declare class BooleanAchievement extends Achievement {
+    toConfig(): SimpleAchievementConfig;
+}
+/**
+ * Value-based achievement (character class, difficulty, etc.)
+ */
+declare class ValueAchievement extends Achievement {
+    private value;
+    constructor(metric: string, value: string, defaultAward: AwardDetails);
+    toConfig(): SimpleAchievementConfig;
+}
+/**
+ * Complex achievement builder for power users (Tier 3)
+ */
+declare class ComplexAchievementBuilder {
+    private id;
+    private metric;
+    private condition;
+    private award;
+    /**
+     * Set the unique identifier for this achievement
+     */
+    withId(id: string): ComplexAchievementBuilder;
+    /**
+     * Set the metric this achievement tracks
+     */
+    withMetric(metric: string): ComplexAchievementBuilder;
+    /**
+     * Set the condition function that determines if achievement is unlocked
+     */
+    withCondition(fn: (value: AchievementMetricValue, state: AchievementState) => boolean): ComplexAchievementBuilder;
+    /**
+     * Set the award details for this achievement
+     */
+    withAward(award: AwardDetails): ComplexAchievementBuilder;
+    /**
+     * Build the final achievement configuration
+     */
+    build(): SimpleAchievementConfig;
+}
+/**
+ * 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
+ */
+declare class AchievementBuilder {
+    /**
+     * Create a single score achievement with smart defaults
+     * @param threshold - Score threshold to achieve
+     * @returns Chainable ThresholdAchievement
+     */
+    static createScoreAchievement(threshold: number): ThresholdAchievement;
+    /**
+     * Create multiple score achievements
+     * @param thresholds - Array of thresholds or [threshold, award] tuples
+     * @returns Complete SimpleAchievementConfig
+     */
+    static createScoreAchievements(thresholds: (number | [number, AwardDetails])[]): SimpleAchievementConfig;
+    /**
+     * Create a single level achievement with smart defaults
+     * @param level - Level threshold to achieve
+     * @returns Chainable ThresholdAchievement
+     */
+    static createLevelAchievement(level: number): ThresholdAchievement;
+    /**
+     * Create multiple level achievements
+     * @param levels - Array of levels or [level, award] tuples
+     * @returns Complete SimpleAchievementConfig
+     */
+    static createLevelAchievements(levels: (number | [number, AwardDetails])[]): SimpleAchievementConfig;
+    /**
+     * Create a boolean achievement with smart defaults
+     * @param metric - The metric name (e.g., 'completedTutorial')
+     * @returns Chainable BooleanAchievement
+     */
+    static createBooleanAchievement(metric: string): BooleanAchievement;
+    /**
+     * 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: string, value: string): ValueAchievement;
+    /**
+     * Create a complex achievement builder for power users
+     * @returns ComplexAchievementBuilder for full control
+     */
+    static create(): ComplexAchievementBuilder;
+    /**
+     * Combine multiple achievement configurations
+     * @param achievements - Array of SimpleAchievementConfig objects or Achievement instances
+     * @returns Combined SimpleAchievementConfig
+     */
+    static combine(achievements: (SimpleAchievementConfig | Achievement)[]): SimpleAchievementConfig;
+}
+
+export { AchievementBuilder, AchievementCondition, AchievementConfiguration, AchievementConfigurationType, AchievementContext, AchievementContextValue, AchievementDetails, AchievementMetricArrayValue, AchievementMetricValue, AchievementMetrics, AchievementProvider, AchievementProviderProps$1 as AchievementProviderProps, AchievementState, AchievementStorage, AwardDetails, BadgesButton, BadgesModal, ConfettiWrapper, CustomAchievementDetails, InitialAchievementMetrics, LocalStorage, MemoryStorage, SimpleAchievementConfig, SimpleAchievementDetails, StorageType, StylesProps, defaultAchievementIcons, defaultStyles, isSimpleConfig, normalizeAchievements, useAchievements, useSimpleAchievements };

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 = {} }) => {
@@ -406,29 +349,6 @@ function normalizeAchievements(config) {
     return normalized;
 }
 
-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 AchievementContext = createContext(undefined);
 const AchievementProvider = ({ achievements: achievementsConfig, storage = StorageType.Local, children, icons = {}, }) => {
     // Normalize the configuration to the complex format
@@ -764,5 +684,291 @@ const defaultStyles = {
     },
 };
 
-export { AchievementContext, AchievementProvider, BadgesButton, BadgesModal, ConfettiWrapper, LocalStorage, StorageType, defaultAchievementIcons, defaultStyles, isSimpleConfig, normalizeAchievements, useAchievements, useSimpleAchievements };
+/**
+ * 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