react-achievements 1.3.7 → 2.0.5

package/README.md

@@ -1,6 +1,5 @@
 <h1 align="center">🏆 React-Achievements 🏆</h1>
 
-
 A flexible and customizable achievement system for React applications, perfect for adding gamification elements to your projects.
 
 ![React Achievements Demo](https://github.com/dave-b-b/react-achievements/blob/main/images/demo.gif?raw=true)
@@ -9,19 +8,18 @@ If you want to test the package, you can try it out here:
 
 https://stackblitz.com/edit/vitejs-vite-sccdux
 
-
 <h2 align="center">🚀 Installation</h2>
 
 Install `react-achievements` using npm or yarn:
 
 ```bash
-npm install react-achievements
+npm install react react-dom @reduxjs/toolkit react-achievements
 ```
 
 or
 
 ```bash
-yarn add react-achievements
+yarn add react react-dom @reduxjs/toolkit react-achievements
 ```
 
 <h2 align="center">🎮 Usage</h2>
@@ -34,89 +32,129 @@ First, wrap your app or a part of your app with the AchievementProvider:
 
 ```jsx
 import React from 'react';
+import { Provider } from 'react-redux';
+import store from './store'; // Import the Redux store you will create
 import { AchievementProvider } from 'react-achievements';
-import achievementConfig from './achievementConfig';
-import Game from './Game';
+import Game from './Game'; // Your main game component
+import achievementConfig from './achievementConfig'; // Your achievement configuration
 
 const initialState = {
-  level: 1,
-  experience: 0,
-  monstersDefeated: 0,
-  questsCompleted: 0
+    level: 1,
+    experience: 0,
+    monstersDefeated: 0,
+    questsCompleted: 0,
+    // Add any other initial metrics here
 };
 
 function App() {
-  return (
-    <AchievementProvider 
-      config={achievementConfig} 
-      initialState={initialState}
-      badgesButtonPosition="top-right"
-    >
-      <Game />
-    </AchievementProvider>
-  );
+    return (
+        <Provider store={store}>
+            <AchievementProvider
+                config={achievementConfig} // Required: your achievement configuration
+                initialState={initialState} // Required: initial game metrics. This can be loaded from your server
+                storageKey="my-game-achievements" // Optional: customize local storage key
+                badgesButtonPosition="top-right" // Optional: customize badges button position
+                // Optional: add custom styles and icons here
+            >
+                <Game />
+            </AchievementProvider>
+        </Provider>
+    );
 }
 
 export default App;
 ```
 
+<h3 align="center">🛠 Set up the Store</h3>
+
+You need to create a store for you state
+
+```tsx
+// src/store.ts
+// src/store.js
+
+import { configureStore } from '@reduxjs/toolkit';
+import achievementReducer from 'react-achievements/redux/achievementSlice';
+import notificationReducer from 'react-achievements/redux/notificationSlice';
+
+const store = configureStore({
+  reducer: {
+    achievements: achievementReducer,
+    notifications: notificationReducer,
+  },
+});
+
+// If you are using JavaScript, you don't need to explicitly export RootState and AppDispatch types.
+export type RootState = ReturnType<typeof store.getState>;
+export type AppDispatch = typeof store.dispatch;
+
+export default store;
+```
+
 <h3 align="center">📝 Create an achievement configuration</h3>
 
 Create a file (e.g., achievementConfig.js) to define your achievements:
 
 ```javascript
+// achievementConfig.js
 import levelUpIcon from './icons/level-up.png';
 import monsterSlayerIcon from './icons/monster-slayer.png';
 import questMasterIcon from './icons/quest-master.png';
 
 const achievementConfig = {
-  level: [
-    {
-      check: (value) => value >= 1,
-      data: {
-        id: 'level_1',
-        title: 'Novice Adventurer',
-        description: 'Reached level 1',
-        icon: levelUpIcon
-      }
-    },
-    {
-      check: (value) => value >= 5,
-      data: {
-        id: 'level_5',
-        title: 'Seasoned Warrior',
-        description: 'Reached level 5',
-        icon: levelUpIcon
-      }
-    }
-  ],
-  monstersDefeated: [
-    {
-      check: (value) => value >= 10,
-      data: {
-        id: 'monster_slayer',
-        title: 'Monster Slayer',
-        description: 'Defeated 10 monsters',
-        icon: monsterSlayerIcon
-      }
-    }
-  ],
-  questsCompleted: [
-    {
-      check: (value) => value >= 1,
-      data: {
-        id: 'quest_master',
-        title: 'Quest Master',
-        description: 'Completed 1 quest',
-        icon: questMasterIcon
-      }
-    }
-  ]
+    level: [
+        {
+            isConditionMet: (value) => value >= 1,
+            achievementDetails: {
+                achievementId: 'level_1',
+                achievementTitle: 'Novice Adventurer',
+                achievementDescription: 'Reached level 1',
+                achievementIconKey: 'levelUpIcon', 
+            },
+        },
+        {
+            isConditionMet: (value) => value >= 5,
+            achievementDetails: {
+                achievementId: 'level_5',
+                achievementTitle: 'Seasoned Warrior',
+                achievementDescription: 'Reached level 5',
+                achievementIconKey: 'levelUpIcon',
+            },
+        },
+    ],
+    monstersDefeated: [
+        {
+            isConditionMet: (value) => value >= 10,
+            achievementDetails: {
+                achievementId: 'monster_slayer',
+                achievementTitle: 'Monster Slayer',
+                achievementDescription: 'Defeated 10 monsters',
+                achievementIconKey: 'monsterSlayerIcon',
+            },
+        },
+    ],
+    questsCompleted: [
+        {
+            isConditionMet: (value) => value >= 1,
+            achievementDetails: {
+                achievementId: 'quest_master',
+                achievementTitle: 'Quest Master',
+                achievementDescription: 'Completed 1 quest',
+                achievementIconKey: 'questMasterIcon',
+            },
+        },
+    ],
 };
 
 export default achievementConfig;
 ```
 
+Key points:
+
+- `isConditionMet`: A function that determines if an achievement should be unlocked.
+- `achievementDetails`: An object containing the details of the achievement.
+- `achievementIconKey`: A string used to reference the icon in the `AchievementProvider`'s icons prop. A list of icons are already provided by the library.
+
 <h3 align="center">🎣 Use the useAchievement hook</h3>
 
 In your game components, use the useAchievement hook to update metrics and trigger achievement checks:
@@ -125,66 +163,58 @@ import React, { useState } from 'react';
 import { useAchievement } from 'react-achievements';
 
 function Game() {
-  const { setMetrics, metrics } = useAchievement();
-  const [currentQuest, setCurrentQuest] = useState(null);
-
-  const defeatMonster = () => {
-    setMetrics(prevMetrics => {
-      const newExperience = prevMetrics.experience + 10;
-      const newLevel = Math.floor(newExperience / 100) + 1;
-      return {
-        ...prevMetrics,
-        monstersDefeated: prevMetrics.monstersDefeated + 1,
-        experience: newExperience,
-        level: newLevel > prevMetrics.level ? newLevel : prevMetrics.level
-      };
-    });
-  };
-
-  const completeQuest = () => {
-    setMetrics(prevMetrics => {
-      const newExperience = prevMetrics.experience + 50;
-      const newLevel = Math.floor(newExperience / 100) + 1;
-      return {
-        ...prevMetrics,
-        questsCompleted: prevMetrics.questsCompleted + 1,
-        experience: newExperience,
-        level: newLevel > prevMetrics.level ? newLevel : prevMetrics.level
-      };
-    });
-    setCurrentQuest(null);
-  };
-
-  const startQuest = () => {
-    setCurrentQuest("Defeat the Dragon");
-  };
-
-  return (
-    <div>
-      <h1>My RPG Game</h1>
-      <p>Level: {metrics.level}</p>
-      <p>Experience: {metrics.experience}</p>
-      <p>Monsters Defeated: {metrics.monstersDefeated}</p>
-      <p>Quests Completed: {metrics.questsCompleted}</p>
-      
-      <div>
-        <h2>Battle Arena</h2>
-        <button onClick={defeatMonster}>Fight a Monster</button>
-      </div>
-
-      <div>
-        <h2>Quest Board</h2>
-        {currentQuest ? (
-          <>
-            <p>Current Quest: {currentQuest}</p>
-            <button onClick={completeQuest}>Complete Quest</button>
-          </>
-        ) : (
-          <button onClick={startQuest}>Start a New Quest</button>
-        )}
-      </div>
-    </div>
-  );
+    const { setMetrics, metrics } = useAchievement();
+    const [currentQuest, setCurrentQuest] = useState(null);
+
+    const defeatMonster = () => {
+        setMetrics((prevMetrics) => ({
+            ...prevMetrics,
+            monstersDefeated: prevMetrics.monstersDefeated + 1,
+            experience: prevMetrics.experience + 10,
+            level: Math.floor((prevMetrics.experience + 10) / 100) + 1, // Calculate new level
+        }));
+    };
+
+    const completeQuest = () => {
+        setMetrics((prevMetrics) => ({
+            ...prevMetrics,
+            questsCompleted: prevMetrics.questsCompleted + 1,
+            experience: prevMetrics.experience + 50,
+            level: Math.floor((prevMetrics.experience + 50) / 100) + 1, // Calculate new level
+        }));
+        setCurrentQuest(null);
+    };
+
+    const startQuest = () => {
+        setCurrentQuest("Defeat the Dragon");
+    };
+
+    return (
+        <div>
+            <h1>My RPG Game</h1>
+            <p>Level: {metrics.level}</p>
+            <p>Experience: {metrics.experience}</p>
+            <p>Monsters Defeated: {metrics.monstersDefeated}</p>
+            <p>Quests Completed: {metrics.questsCompleted}</p>
+
+            <div>
+                <h2>Battle Arena</h2>
+                <button onClick={defeatMonster}>Fight a Monster</button>
+            </div>
+
+            <div>
+                <h2>Quest Board</h2>
+                {currentQuest ? (
+                    <>
+                        <p>Current Quest: {currentQuest}</p>
+                        <button onClick={completeQuest}>Complete Quest</button>
+                    </>
+                ) : (
+                    <button onClick={startQuest}>Start a New Quest</button>
+                )}
+            </div>
+        </div>
+    );
 }
 
 export default Game;
@@ -193,12 +223,15 @@ export default Game;
 <h2 align="center">✨ Features</h2>
 
 - Flexible Achievement System: Define custom metrics and achievement conditions for your game or app.
+- Built with TypeScript: Provides strong typing and improved developer experience.
+- Redux-Powered State Management: Leverages Redux for predictable and scalable state management of achievements and metrics.
 - Automatic Achievement Tracking: Achievements are automatically checked and unlocked when metrics change.
 - Achievement Notifications: A modal pops up when an achievement is unlocked, perfect for rewarding players.
 - Persistent Achievements: Unlocked achievements and metrics are stored in local storage, allowing players to keep their progress.
 - Achievement Gallery: Players can view all their unlocked achievements, encouraging completionism.
 - Confetti Effect: A celebratory confetti effect is displayed when an achievement is unlocked, adding to the excitement.
-- Local Storage: Achievements are stored locally on the device
+- Local Storage: Achievements are stored locally on the device.
+- **Programmatic Reset:** Includes a `resetStorage` function accessible via the `useAchievementContext` hook to easily reset all achievement data.
 
 <h2 align="center">🔧 API</h2>
 
@@ -216,10 +249,9 @@ export default Game;
 
 #### Returns an object with:
 
-- `setMetrics`: Function to update the metrics.
-- `metrics`: Current metrics object.
-- `unlockedAchievements`: Array of unlocked achievement IDs.
-- `showBadgesModal`: Function to manually show the badges modal.
+- `updateMetrics`: Function to update the metrics. Accepts either a new metrics object or a function that receives the previous metrics and returns the new metrics.
+- `unlockedAchievements`: Array of unlocked achievement IDs. (Note: Access the actual Redux state using `useSelector`).
+- `resetStorage`: Function to clear all achievement data from local storage and reset the Redux state.
 
 <h2 align="center">🎨 Customization</h2>
 
@@ -228,25 +260,13 @@ React-Achievements allows for extensive customization of its appearance. You can
 ```jsx
 const customStyles = {
   achievementModal: {
-    overlay: {
-      backgroundColor: 'rgba(0, 0, 0, 0.8)',
-    },
-    content: {
-      backgroundColor: '#2a2a2a',
-      color: '#ffffff',
-    },
-    title: {
-      color: '#ffd700',
-    },
-    button: {
-      backgroundColor: '#4CAF50',
-    },
+    // Custom styles for the achievement modal below
   },
   badgesModal: {
-    // Custom styles for the badges modal
+    // Custom styles for the badges modal below
   },
   badgesButton: {
-    // Custom styles for the badges button
+    // Custom styles for the badges button below
   },
 };
 
@@ -263,7 +283,7 @@ function App() {
 }
 ```
 
-### achievementModal
+### achievementModal (to be passed in as a customStyle above)
 
 Customizes the modal that appears when an achievement is unlocked.
 
@@ -311,7 +331,7 @@ achievementModal: {
 }
 ```
 
-### badgesModal
+### badgesModal (to be passed in as a customStyle above)
 
 ```
 badgesModal: {
@@ -352,7 +372,7 @@ badgesModal: {
 ```
 
 
-### badgesButton
+### badgesButton (to be passed in as a customStyle above)
 
 ```
 badgesButton: {
@@ -372,10 +392,126 @@ badgesButton: {
 
 <h2 align="center">Resetting React Achievements</h2>
 
-The achievements are stored in local storage. In order to reset the package in your app, you need to delete the key-value pairs in local storage:
+The achievements and metrics are managed by Redux and persisted in local storage. You have two primary ways to reset the achievement system:
+
+1.  **Programmatic Reset:** Use the `resetStorage` function provided by the `useAchievementContext` hook within your components:
 
-![Key-Value pair delete image](https://github.com/dave-b-b/react-achievements/blob/main/images/delete_local_storage.png?raw=true)
+```jsx
+    import React from 'react';
+    import { useAchievementContext } from 'react-achievements';
+
+    function ResetButton() {
+      const { resetStorage } = useAchievementContext();
+
+      const handleReset = () => {
+        resetStorage();
+        console.log('Achievements and progress reset!');
+      };
+
+      return <button onClick={handleReset}>Reset Achievements</button>;
+    }
+```
+
+<h2 align="center">🏆Available Icons🏆</h2>
 
+```
+// 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
+    trophy: '🏆',
+    star: '⭐',
+    flag: '🚩',
+    puzzle: '🧩',
+    gem: '💎',
+    crown: '👑',
+    medal: '🏅',
+    ribbon: '🎗️',
+    badge: '🎖️',
+    shield: '🛡️',
+```
 
 <h2 align="center">📄 License</h2>
 MIT

package/coverage/clover.xml

@@ -64,7 +64,7 @@
     </package>
     <package name="src.context">
       <metrics statements="59" coveredstatements="0" conditionals="15" coveredconditionals="0" methods="21" coveredmethods="0"/>
-      <file name="AchievementContext.tsx" path="/Users/daves-mbp/Projects/react-achievements/src/context/AchievementContext.tsx">
+      <file name="AchievementProvider.tsx" path="/Users/daves-mbp/Projects/react-achievements/src/context/AchievementProvider.tsx">
         <metrics statements="59" coveredstatements="0" conditionals="15" coveredconditionals="0" methods="21" coveredmethods="0"/>
         <line num="1" count="0" type="stmt"/>
         <line num="3" count="0" type="stmt"/>

package/coverage/lcov-report/src/context/AchievementContext.tsx.html

@@ -3,7 +3,7 @@
 <html lang="en">
 
 <head>
-    <title>Code coverage report for src/context/AchievementContext.tsx</title>
+    <title>Code coverage report for src/context/AchievementProvider.tsx</title>
     <meta charset="utf-8" />
     <link rel="stylesheet" href="../../prettify.css" />
     <link rel="stylesheet" href="../../base.css" />
@@ -19,7 +19,7 @@
 <body>
 <div class='wrapper'>
     <div class='pad1'>
-        <h1><a href="../../index.html">All files</a> / <a href="index.html">src/context</a> AchievementContext.tsx</h1>
+        <h1><a href="../../index.html">All files</a> / <a href="index.html">src/context</a> AchievementProvider.tsx</h1>
         <div class='clearfix'>
             
             <div class='fl pad1y space-right2'>
@@ -366,7 +366,7 @@ interface AchievementProviderProps {
     badgesButtonPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
 }
 &nbsp;
-const AchievementContext = <span class="cstat-no" title="statement not covered" >createContext&lt;AchievementContextProps | undefined&gt;(undefined);</span>
+const AchievementProvider = <span class="cstat-no" title="statement not covered" >createContext&lt;AchievementContextProps | undefined&gt;(undefined);</span>
 &nbsp;
 export const <span class="cstat-no" title="statement not covered" >AchievementProvider: React.FC&lt;AchievementProviderProps&gt; = <span class="cstat-no" title="statement not covered" ><span class="fstat-no" title="function not covered" >(</span>{</span></span>
                                                                             children,
@@ -456,7 +456,7 @@ export const <span class="cstat-no" title="statement not covered" >AchievementPr
     };
 &nbsp;
 <span class="cstat-no" title="statement not covered" >    return (</span>
-        &lt;AchievementContext.Provider value={contextValue}&gt;
+        &lt;AchievementProvider.Provider value={contextValue}&gt;
             {children}
             &lt;AchievementModal
                 show={!!newAchievement}
@@ -473,12 +473,12 @@ export const <span class="cstat-no" title="statement not covered" >AchievementPr
             /&gt;
             &lt;BadgesButton onClick={showBadgesModal} position={badgesButtonPosition} /&gt;
             &lt;ConfettiWrapper show={showConfetti} /&gt;
-        &lt;/AchievementContext.Provider&gt;
+        &lt;/AchievementProvider.Provider&gt;
     );
 };
 &nbsp;
 export const <span class="cstat-no" title="statement not covered" >useAchievement = <span class="cstat-no" title="statement not covered" ><span class="fstat-no" title="function not covered" >(</span>) =</span>&gt; {</span>
-    const context = <span class="cstat-no" title="statement not covered" >useContext(AchievementContext);</span>
+    const context = <span class="cstat-no" title="statement not covered" >useContext(AchievementProvider);</span>
 <span class="cstat-no" title="statement not covered" >    <span class="missing-if-branch" title="if path not taken" >I</span>if (context === undefined) {</span>
 <span class="cstat-no" title="statement not covered" >        throw new Error('useAchievement must be used within an AchievementProvider');</span>
     }

package/coverage/lcov-report/src/context/index.html

@@ -79,7 +79,7 @@
 </tr>
 </thead>
 <tbody><tr>
-	<td class="file low" data-value="AchievementContext.tsx"><a href="AchievementContext.tsx.html">AchievementContext.tsx</a></td>
+	<td class="file low" data-value="AchievementProvider.tsx"><a href="AchievementProvider.tsx.html">AchievementProvider.tsx</a></td>
 	<td data-value="0" class="pic low">
 	<div class="chart"><div class="cover-fill" style="width: 0%"></div><div class="cover-empty" style="width: 100%"></div></div>
 	</td>

package/coverage/lcov-report/src/index.ts.html

@@ -87,7 +87,7 @@
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-no">&nbsp;</span>
-<span class="cline-any cline-neutral">&nbsp;</span></td><td class="text"><pre class="prettyprint lang-js"><span class="cstat-no" title="statement not covered" >import { A</span>chievementProvider, useAchievement } from './context/AchievementContext';
+<span class="cline-any cline-neutral">&nbsp;</span></td><td class="text"><pre class="prettyprint lang-js"><span class="cstat-no" title="statement not covered" >import { A</span>chievementProvider, useAchievement } from './context/AchievementProvider';
 import { Metrics, AchievementConfig, AchievementData, AchievementCondition } from './types';
 <span class="cstat-no" title="statement not covered" >import C</span>onfettiWrapper from './components/ConfettiWrapper';
 &nbsp;

package/coverage/lcov.info

@@ -114,7 +114,7 @@ BRF:1
 BRH:0
 end_of_record
 TN:
-SF:src/context/AchievementContext.tsx
+SF:src/context/AchievementProvider.tsx
 FN:26,(anonymous_7)
 FN:33,(anonymous_8)
 FN:34,(anonymous_9)