react-achievements 3.0.2 → 3.2.0

package/dist/index.d.ts

@@ -23,6 +23,20 @@ interface AchievementCondition {
 interface AchievementConfiguration {
     [key: string]: AchievementCondition[];
 }
+interface SimpleAchievementDetails {
+    title: string;
+    description?: string;
+    icon?: string;
+}
+interface CustomAchievementDetails extends SimpleAchievementDetails {
+    condition: (metrics: Record<string, any>) => boolean;
+}
+interface SimpleAchievementConfig {
+    [metric: string]: {
+        [threshold: string]: SimpleAchievementDetails | CustomAchievementDetails;
+    };
+}
+type AchievementConfigurationType = AchievementConfiguration | SimpleAchievementConfig;
 interface InitialAchievementMetrics {
     [key: string]: AchievementMetricValue;
 }
@@ -90,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';
@@ -126,7 +151,7 @@ interface AchievementContextType {
 }
 declare const AchievementContext: React$1.Context<AchievementContextType | undefined>;
 interface AchievementProviderProps {
-    achievements: AchievementConfiguration;
+    achievements: AchievementConfigurationType;
     storage?: AchievementStorage | StorageType;
     children: React$1.ReactNode;
     icons?: Record<string, string>;
@@ -135,88 +160,193 @@ declare const AchievementProvider: React$1.FC<AchievementProviderProps>;
 
 declare const useAchievements: () => AchievementContextType;
 
+/**
+ * A simplified hook for achievement tracking.
+ * Provides an easier API for common use cases while maintaining access to advanced features.
+ */
+declare const useSimpleAchievements: () => {
+    /**
+     * Track a metric value for achievements
+     * @param metric - The metric name (e.g., 'score', 'level')
+     * @param value - The metric value
+     */
+    track: (metric: string, value: any) => void;
+    /**
+     * Track multiple metrics at once
+     * @param metrics - Object with metric names as keys and values
+     */
+    trackMultiple: (metrics: Record<string, any>) => void;
+    /**
+     * Array of unlocked achievement IDs
+     */
+    unlocked: string[];
+    /**
+     * All available achievements
+     */
+    all: Record<string, any>;
+    /**
+     * Number of unlocked achievements
+     */
+    unlockedCount: number;
+    /**
+     * Reset all achievement progress
+     */
+    reset: () => void;
+    /**
+     * Get current state (advanced usage)
+     */
+    getState: () => {
+        metrics: AchievementMetrics;
+        unlocked: string[];
+    };
+};
+
 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;
 };
 
-export { AchievementCondition, AchievementConfiguration, AchievementContext, AchievementContextValue, AchievementDetails, AchievementMetricArrayValue, AchievementMetricValue, AchievementMetrics, AchievementProvider, AchievementProviderProps$1 as AchievementProviderProps, AchievementState, AchievementStorage, BadgesButton, BadgesModal, ConfettiWrapper, InitialAchievementMetrics, LocalStorage, StorageType, StylesProps, defaultAchievementIcons, defaultStyles, useAchievements };
+declare function isSimpleConfig(config: AchievementConfigurationType): config is SimpleAchievementConfig;
+declare function normalizeAchievements(config: AchievementConfigurationType): AchievementConfiguration;
+
+/**
+ * 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 };