react-achievements 3.1.0 → 3.2.1

package/dist/types/hooks/useSimpleAchievements.d.ts

@@ -9,6 +9,12 @@ export declare const useSimpleAchievements: () => {
      * @param value - The metric value
      */
     track: (metric: string, value: any) => void;
+    /**
+     * Increment a numeric metric by a specified amount
+     * @param metric - The metric name (e.g., 'buttonClicks', 'score')
+     * @param amount - The amount to increment by (defaults to 1)
+     */
+    increment: (metric: string, amount?: number) => void;
     /**
      * Track multiple metrics at once
      * @param metrics - Object with metric names as keys and values

package/dist/types/index.d.ts

@@ -1,5 +1,6 @@
 export type { AchievementMetrics, AchievementConfiguration, AchievementConfigurationType, SimpleAchievementConfig, SimpleAchievementDetails, CustomAchievementDetails, AchievementDetails, AchievementCondition, AchievementMetricValue, AchievementMetricArrayValue, InitialAchievementMetrics, AchievementState, AchievementStorage, AchievementContextValue, StylesProps, AchievementProviderProps, } from './core/types';
 export { LocalStorage } from './core/storage/LocalStorage';
+export { MemoryStorage } from './core/storage/MemoryStorage';
 export { StorageType } from './core/types';
 export { BadgesButton } from './core/components/BadgesButton';
 export { BadgesModal } from './core/components/BadgesModal';
@@ -10,3 +11,4 @@ export { useSimpleAchievements } from './hooks/useSimpleAchievements';
 export { defaultStyles } from './core/styles/defaultStyles';
 export { defaultAchievementIcons } from './core/icons/defaultIcons';
 export { normalizeAchievements, isSimpleConfig } from './core/utils/configNormalizer';
+export { AchievementBuilder, type AwardDetails, } from './utils/achievementHelpers';

package/dist/types/utils/achievementHelpers.d.ts

@@ -0,0 +1,135 @@
+import { SimpleAchievementConfig, AchievementMetricValue, AchievementState } from '../core/types';
+/**
+ * Helper interface for cleaner achievement award definitions
+ */
+export 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
+ */
+export 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 {};

package/package.json

@@ -1,12 +1,17 @@
 {
   "name": "react-achievements",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "description": "Core achievement system for React applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "rollup -c",
-    "test": "jest",
+    "test": "npm run type-check && jest",
+    "test:unit": "jest",
+    "type-check": "tsc --noEmit --project tsconfig.test.json",
+    "type-check:watch": "tsc --noEmit --watch --project tsconfig.test.json",
+    "type-check:src": "tsc --noEmit",
+    "type-check:stories": "find stories -name '*.tsx' -o -name '*.ts' | xargs tsc --noEmit --jsx react --esModuleInterop --skipLibCheck",
     "prepare": "npm run build",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build"