react-achievements 2.0.3 → 2.1.0

package/README.md

@@ -13,13 +13,13 @@ https://stackblitz.com/edit/vitejs-vite-sccdux
 Install `react-achievements` using npm or yarn:
 
 ```bash
-npm install react react-dom react-redux @reduxjs/toolkit react-achievements
+npm install react react-dom @reduxjs/toolkit react-achievements
 ```
 
 or
 
 ```bash
-yarn add react react-dom react-redux @reduxjs/toolkit react-achievements
+yarn add react react-dom @reduxjs/toolkit react-achievements
 ```
 
 <h2 align="center">🎮 Usage</h2>
@@ -43,6 +43,7 @@ const initialState = {
     experience: 0,
     monstersDefeated: 0,
     questsCompleted: 0,
+    previouslyAwardedAchievements: ['first_step'], // Optional: Load previously awarded achievements
     // Add any other initial metrics here
 };
 
@@ -51,7 +52,7 @@ function App() {
         <Provider store={store}>
             <AchievementProvider
                 config={achievementConfig} // Required: your achievement configuration
-                initialState={initialState} // Required: initial game metrics. This can be loaded from your server
+                initialState={initialState} // Required: initial game metrics and optionally previously awarded achievements. 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
@@ -231,6 +232,7 @@ export default Game;
 - 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.
+- **Loading Previous Awards:** The AchievementProvider accepts an optional previouslyAwardedAchievements array in its initialState prop, allowing you to load achievements that the user has already earned.
 - **Programmatic Reset:** Includes a `resetStorage` function accessible via the `useAchievementContext` hook to easily reset all achievement data.
 
 <h2 align="center">🔧 API</h2>
@@ -240,7 +242,7 @@ export default Game;
 #### Props:
 
 - `config`: An object defining your metrics and achievements.
-- `initialState`: The initial state of your metrics.
+- `initialState`: The initial state of your metrics. Can also include an optional previouslyAwardedAchievements array of achievement IDs.
 - `storageKey` (optional): A string to use as the key for localStorage. Default: 'react-achievements'
 - `badgesButtonPosition` (optional): Position of the badges button. Default: 'top-right'
 - `styles` (optional): Custom styles for the achievement components.
@@ -253,6 +255,56 @@ export default Game;
 - `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.
 
+<h3 align="center">🪝 useAchievementState Hook</h3>
+<h4 align="center">Returns an object containing the current achievement state, useful for saving to a server or other persistent storage.
+</h4>
+
+
+#### Returns an object with:
+
+- `metrics`: The current achievement metrics object.
+- `previouslyAwardedAchievements`: An array of achievement IDs that have been previously awarded to the user.
+
+**Example Usage:**
+
+```jsx
+import React from 'react';
+import { useAchievementState } from 'react-achievements';
+
+const SyncAchievementsButton = () => {
+    const { metrics, previouslyAwardedAchievements } = useAchievementState();
+
+    const handleSaveToServer = async () => {
+        const achievementData = {
+            metrics,
+            previouslyAwardedAchievements,
+        };
+        try {
+            const response = await fetch('/api/save-achievements', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(achievementData),
+            });
+            if (response.ok) {
+                console.log('Achievement data saved successfully!');
+            } else {
+                console.error('Failed to save achievement data.');
+            }
+        } catch (error) {
+            console.error('Error saving achievement data:', error);
+        }
+    };
+
+    return (
+        <button onClick={handleSaveToServer}>Save Achievements to Server</button>
+    );
+};
+
+export default SyncAchievementsButton;
+```
+
 <h2 align="center">🎨 Customization</h2>
 
 React-Achievements allows for extensive customization of its appearance. You can override the default styles by passing a `styles` prop to the `AchievementProvider`:
@@ -412,6 +464,154 @@ The achievements and metrics are managed by Redux and persisted in local storage
     }
 ```
 
+<h2 align="center">💾 Saving and Loading Progress</h2>
+
+<h4 align="center">To persist user achievement progress across sessions or devices, you'll typically want to save the `metrics` and `previouslyAwardedAchievements` from your Redux store to your server. You can use the `useAchievementState` hook to access this data and trigger the save operation, for example, when the user logs out:
+</h4>
+
+```jsx
+import React from 'react';
+import { useAchievementState } from 'react-achievements/hooks/useAchievementState';
+
+const LogoutButtonWithSave = ({ onLogout }) => {
+    const { metrics, previouslyAwardedAchievements } = useAchievementState();
+
+    const handleLogoutAndSave = async () => {
+        const achievementData = {
+            metrics,
+            previouslyAwardedAchievements,
+        };
+        try {
+            const response = await fetch('/api/save-achievements', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    // Include any necessary authentication headers
+                },
+                body: JSON.stringify(achievementData),
+            });
+            if (response.ok) {
+                console.log('Achievement data saved successfully before logout!');
+            } else {
+                console.error('Failed to save achievement data before logout.');
+            }
+        } catch (error) {
+            console.error('Error saving achievement data:', error);
+        } finally {
+            // Proceed with the logout action regardless of save success
+            onLogout();
+        }
+    };
+
+    return (
+        <button onClick={handleLogoutAndSave}>Logout</button>
+    );
+};
+
+export default LogoutButtonWithSave;
+```
+
+<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/dist/hooks/useAchievementState.d.ts

@@ -0,0 +1,4 @@
+export declare const useAchievementState: () => {
+    metrics: import("..").AchievementMetrics;
+    previouslyAwardedAchievements: string[];
+};

package/dist/index.cjs.js

@@ -1832,10 +1832,12 @@ typeof queueMicrotask === "function" ? queueMicrotask.bind(typeof window !== "un
 // src/index.ts
 F();
 
+// src/redux/achievementSlice.ts
 const initialState$1 = {
     config: {},
     metrics: {},
     unlockedAchievements: [],
+    previouslyAwardedAchievements: [], // Initialize as empty
     storageKey: null,
 };
 const achievementSlice = createSlice({
@@ -1843,51 +1845,67 @@ const achievementSlice = createSlice({
     initialState: initialState$1,
     reducers: {
         initialize: (state, action) => {
-            var _a, _b;
+            var _a, _b, _c, _d;
             state.config = action.payload.config;
             state.storageKey = action.payload.storageKey;
             const storedState = action.payload.storageKey ? localStorage.getItem(action.payload.storageKey) : null;
+            const initialMetrics = action.payload.initialState ? Object.keys(action.payload.initialState)
+                .filter(key => key !== 'previouslyAwardedAchievements')
+                .reduce((acc, key) => (Object.assign(Object.assign({}, acc), { [key]: Array.isArray(action.payload.initialState[key]) ? action.payload.initialState[key] : [action.payload.initialState[key]] })), {}) : {};
+            const initialAwarded = ((_a = action.payload.initialState) === null || _a === void 0 ? void 0 : _a.previouslyAwardedAchievements) || [];
             if (storedState) {
                 try {
                     const parsedState = JSON.parse(storedState);
-                    state.metrics = ((_a = parsedState.achievements) === null || _a === void 0 ? void 0 : _a.metrics) || {};
-                    state.unlockedAchievements = ((_b = parsedState.achievements) === null || _b === void 0 ? void 0 : _b.unlockedAchievements) || [];
+                    state.metrics = ((_b = parsedState.achievements) === null || _b === void 0 ? void 0 : _b.metrics) || initialMetrics;
+                    state.unlockedAchievements = ((_c = parsedState.achievements) === null || _c === void 0 ? void 0 : _c.unlockedAchievements) || [];
+                    state.previouslyAwardedAchievements = ((_d = parsedState.achievements) === null || _d === void 0 ? void 0 : _d.previouslyAwardedAchievements) || initialAwarded; // Prioritize stored, fallback to initial
                 }
                 catch (error) {
                     console.error('Error parsing stored achievement state:', error);
-                    state.metrics = action.payload.initialState ? Object.keys(action.payload.initialState).reduce((acc, key) => (Object.assign(Object.assign({}, acc), { [key]: Array.isArray(action.payload.initialState[key]) ? action.payload.initialState[key] : [action.payload.initialState[key]] })), {}) : {};
+                    state.metrics = initialMetrics;
                     state.unlockedAchievements = [];
+                    state.previouslyAwardedAchievements = initialAwarded;
                 }
             }
             else {
-                state.metrics = action.payload.initialState ? Object.keys(action.payload.initialState).reduce((acc, key) => (Object.assign(Object.assign({}, acc), { [key]: Array.isArray(action.payload.initialState[key]) ? action.payload.initialState[key] : [action.payload.initialState[key]] })), {}) : {};
+                state.metrics = initialMetrics;
                 state.unlockedAchievements = [];
+                state.previouslyAwardedAchievements = initialAwarded;
             }
         },
         setMetrics: (state, action) => {
             state.metrics = action.payload;
             if (state.storageKey) {
-                localStorage.setItem(state.storageKey, JSON.stringify({ achievements: { metrics: state.metrics, unlockedAchievements: state.unlockedAchievements } }));
+                localStorage.setItem(state.storageKey, JSON.stringify({ achievements: { metrics: state.metrics, unlockedAchievements: state.unlockedAchievements, previouslyAwardedAchievements: state.previouslyAwardedAchievements } }));
             }
         },
         unlockAchievement: (state, action) => {
             if (!state.unlockedAchievements.includes(action.payload)) {
                 state.unlockedAchievements.push(action.payload);
                 if (state.storageKey) {
-                    localStorage.setItem(state.storageKey, JSON.stringify({ achievements: { metrics: state.metrics, unlockedAchievements: state.unlockedAchievements } }));
+                    localStorage.setItem(state.storageKey, JSON.stringify({ achievements: { metrics: state.metrics, unlockedAchievements: state.unlockedAchievements, previouslyAwardedAchievements: state.previouslyAwardedAchievements } }));
+                }
+            }
+        },
+        markAchievementAsAwarded: (state, action) => {
+            if (!state.previouslyAwardedAchievements.includes(action.payload)) {
+                state.previouslyAwardedAchievements.push(action.payload);
+                if (state.storageKey) {
+                    localStorage.setItem(state.storageKey, JSON.stringify({ achievements: { metrics: state.metrics, unlockedAchievements: state.unlockedAchievements, previouslyAwardedAchievements: state.previouslyAwardedAchievements } }));
                 }
             }
         },
         resetAchievements: (state) => {
             state.metrics = {};
             state.unlockedAchievements = [];
+            state.previouslyAwardedAchievements = [];
             if (state.storageKey) {
                 localStorage.removeItem(state.storageKey);
             }
         },
     },
 });
-const { initialize, setMetrics, unlockAchievement, resetAchievements } = achievementSlice.actions;
+const { initialize, setMetrics, unlockAchievement, resetAchievements, markAchievementAsAwarded } = achievementSlice.actions;
 var achievementSlice$1 = achievementSlice.reducer;
 
 const initialState = {
@@ -2262,6 +2280,7 @@ const AchievementProvider = ({ children, config, initialState = {}, storageKey =
     const dispatch = useDispatch();
     const metrics = useSelector((state) => state.achievements.metrics);
     const unlockedAchievementIds = useSelector((state) => state.achievements.unlockedAchievements);
+    const previouslyAwardedAchievementIds = useSelector((state) => state.achievements.previouslyAwardedAchievements);
     const notifications = useSelector((state) => state.notifications.notifications);
     const mergedStyles = React.useMemo(() => mergeDeep(defaultStyles, styles), [styles]);
     const [currentAchievement, setCurrentAchievement] = React.useState(null);
@@ -2279,31 +2298,40 @@ const AchievementProvider = ({ children, config, initialState = {}, storageKey =
         dispatch(initialize({ config, initialState, storageKey }));
     }, [dispatch, config, initialState, storageKey]);
     const checkAchievements = React.useCallback(() => {
-        const newAchievements = [];
+        const newAchievementsToAward = [];
         if (!unlockedAchievementIds) {
             console.error('unlockedAchievements is undefined!');
             return;
         }
-        Object.entries(config).forEach(([metricName, conditions]) => {
+        Object.entries(config)
+            .forEach(([metricName, conditions]) => {
             const metricValues = metrics[metricName];
             if (!metricValues) {
                 return;
             }
-            conditions.forEach((condition) => {
+            conditions
+                .filter(condition => !previouslyAwardedAchievementIds.includes(condition.achievementDetails.achievementId))
+                .forEach((condition) => {
                 if (metricValues.some((value) => condition.isConditionMet(value)) &&
                     !unlockedAchievementIds.includes(condition.achievementDetails.achievementId)) {
-                    newAchievements.push(condition.achievementDetails);
+                    dispatch(unlockAchievement(condition.achievementDetails.achievementId));
+                    newAchievementsToAward.push(condition.achievementDetails);
+                }
+                else if (metricValues.some((value) => condition.isConditionMet(value)) &&
+                    unlockedAchievementIds.includes(condition.achievementDetails.achievementId) &&
+                    !previouslyAwardedAchievementIds.includes(condition.achievementDetails.achievementId)) {
+                    newAchievementsToAward.push(condition.achievementDetails);
                 }
             });
         });
-        if (newAchievements.length > 0) {
-            newAchievements.forEach((achievement) => {
-                dispatch(unlockAchievement(achievement.achievementId));
+        if (newAchievementsToAward.length > 0) {
+            newAchievementsToAward.forEach((achievement) => {
                 dispatch(addNotification(achievement));
+                dispatch(markAchievementAsAwarded(achievement.achievementId));
             });
             setShowConfetti(true);
         }
-    }, [config, metrics, unlockedAchievementIds, dispatch]);
+    }, [config, metrics, unlockedAchievementIds, previouslyAwardedAchievementIds, dispatch]);
     React.useEffect(() => {
         checkAchievements();
     }, [metrics, checkAchievements]);
@@ -2318,7 +2346,8 @@ const AchievementProvider = ({ children, config, initialState = {}, storageKey =
             .filter((c) => achievedIds.includes(c.achievementDetails.achievementId))
             .map((c) => c.achievementDetails));
     }, [config]);
-    const unlockedAchievementsDetails = getAchievements(unlockedAchievementIds);
+    getAchievements(unlockedAchievementIds);
+    const previouslyAwardedAchievementsDetails = getAchievements(previouslyAwardedAchievementIds);
     return (React.createElement(AchievementContext.Provider, { value: { updateMetrics, unlockedAchievements: unlockedAchievementIds, resetStorage } },
         children,
         React.createElement(AchievementModal$1, { isOpen: !!currentAchievement, achievement: currentAchievement, onClose: () => {
@@ -2327,8 +2356,8 @@ const AchievementProvider = ({ children, config, initialState = {}, storageKey =
                     dispatch(clearNotifications());
                 }
             }, styles: mergedStyles.achievementModal, icons: mergedIcons }),
-        React.createElement(BadgesModal$1, { isOpen: showBadges, achievements: unlockedAchievementsDetails, onClose: () => setShowBadges(false), styles: mergedStyles.badgesModal, icons: mergedIcons }),
-        React.createElement(BadgesButton$1, { onClick: showBadgesModal, position: badgesButtonPosition, styles: mergedStyles.badgesButton, unlockedAchievements: unlockedAchievementsDetails }),
+        React.createElement(BadgesModal$1, { isOpen: showBadges, achievements: previouslyAwardedAchievementsDetails, onClose: () => setShowBadges(false), styles: mergedStyles.badgesModal, icons: mergedIcons }),
+        React.createElement(BadgesButton$1, { onClick: showBadgesModal, position: badgesButtonPosition, styles: mergedStyles.badgesButton, unlockedAchievements: previouslyAwardedAchievementsDetails }),
         React.createElement(ConfettiWrapper, { show: showConfetti || notifications.length > 0 })));
 };
 function isObject(item) {
@@ -2354,8 +2383,18 @@ function mergeDeep(target, source) {
     return output;
 }
 
+const useAchievementState = () => {
+    const metrics = useSelector((state) => state.achievements.metrics);
+    const previouslyAwardedAchievements = useSelector((state) => state.achievements.previouslyAwardedAchievements);
+    return {
+        metrics,
+        previouslyAwardedAchievements,
+    };
+};
+
 exports.AchievementProvider = AchievementProvider;
 exports.ConfettiWrapper = ConfettiWrapper;
 exports.achievementReducer = achievementSlice$1;
 exports.notificationReducer = notificationSlice$1;
 exports.useAchievement = useAchievementContext;
+exports.useAchievementState = useAchievementState;

package/dist/index.d.ts

@@ -3,4 +3,5 @@ import { AchievementMetrics, AchievementConfiguration, AchievementDetails, Achie
 import ConfettiWrapper from './components/ConfettiWrapper';
 import achievementReducer from './redux/achievementSlice';
 import notificationReducer from './redux/notificationSlice';
-export { AchievementProvider, useAchievement, AchievementMetrics, AchievementConfiguration, AchievementDetails, AchievementUnlockCondition, ConfettiWrapper, achievementReducer, notificationReducer, };
+import { useAchievementState } from './hooks/useAchievementState';
+export { AchievementProvider, useAchievement, AchievementMetrics, AchievementConfiguration, AchievementDetails, AchievementUnlockCondition, ConfettiWrapper, achievementReducer, notificationReducer, useAchievementState, };

package/dist/index.esm.js

@@ -1812,10 +1812,12 @@ typeof queueMicrotask === "function" ? queueMicrotask.bind(typeof window !== "un
 // src/index.ts
 F();
 
+// src/redux/achievementSlice.ts
 const initialState$1 = {
     config: {},
     metrics: {},
     unlockedAchievements: [],
+    previouslyAwardedAchievements: [], // Initialize as empty
     storageKey: null,
 };
 const achievementSlice = createSlice({
@@ -1823,51 +1825,67 @@ const achievementSlice = createSlice({
     initialState: initialState$1,
     reducers: {
         initialize: (state, action) => {
-            var _a, _b;
+            var _a, _b, _c, _d;
             state.config = action.payload.config;
             state.storageKey = action.payload.storageKey;
             const storedState = action.payload.storageKey ? localStorage.getItem(action.payload.storageKey) : null;
+            const initialMetrics = action.payload.initialState ? Object.keys(action.payload.initialState)
+                .filter(key => key !== 'previouslyAwardedAchievements')
+                .reduce((acc, key) => (Object.assign(Object.assign({}, acc), { [key]: Array.isArray(action.payload.initialState[key]) ? action.payload.initialState[key] : [action.payload.initialState[key]] })), {}) : {};
+            const initialAwarded = ((_a = action.payload.initialState) === null || _a === void 0 ? void 0 : _a.previouslyAwardedAchievements) || [];
             if (storedState) {
                 try {
                     const parsedState = JSON.parse(storedState);
-                    state.metrics = ((_a = parsedState.achievements) === null || _a === void 0 ? void 0 : _a.metrics) || {};
-                    state.unlockedAchievements = ((_b = parsedState.achievements) === null || _b === void 0 ? void 0 : _b.unlockedAchievements) || [];
+                    state.metrics = ((_b = parsedState.achievements) === null || _b === void 0 ? void 0 : _b.metrics) || initialMetrics;
+                    state.unlockedAchievements = ((_c = parsedState.achievements) === null || _c === void 0 ? void 0 : _c.unlockedAchievements) || [];
+                    state.previouslyAwardedAchievements = ((_d = parsedState.achievements) === null || _d === void 0 ? void 0 : _d.previouslyAwardedAchievements) || initialAwarded; // Prioritize stored, fallback to initial
                 }
                 catch (error) {
                     console.error('Error parsing stored achievement state:', error);
-                    state.metrics = action.payload.initialState ? Object.keys(action.payload.initialState).reduce((acc, key) => (Object.assign(Object.assign({}, acc), { [key]: Array.isArray(action.payload.initialState[key]) ? action.payload.initialState[key] : [action.payload.initialState[key]] })), {}) : {};
+                    state.metrics = initialMetrics;
                     state.unlockedAchievements = [];
+                    state.previouslyAwardedAchievements = initialAwarded;
                 }
             }
             else {
-                state.metrics = action.payload.initialState ? Object.keys(action.payload.initialState).reduce((acc, key) => (Object.assign(Object.assign({}, acc), { [key]: Array.isArray(action.payload.initialState[key]) ? action.payload.initialState[key] : [action.payload.initialState[key]] })), {}) : {};
+                state.metrics = initialMetrics;
                 state.unlockedAchievements = [];
+                state.previouslyAwardedAchievements = initialAwarded;
             }
         },
         setMetrics: (state, action) => {
             state.metrics = action.payload;
             if (state.storageKey) {
-                localStorage.setItem(state.storageKey, JSON.stringify({ achievements: { metrics: state.metrics, unlockedAchievements: state.unlockedAchievements } }));
+                localStorage.setItem(state.storageKey, JSON.stringify({ achievements: { metrics: state.metrics, unlockedAchievements: state.unlockedAchievements, previouslyAwardedAchievements: state.previouslyAwardedAchievements } }));
             }
         },
         unlockAchievement: (state, action) => {
             if (!state.unlockedAchievements.includes(action.payload)) {
                 state.unlockedAchievements.push(action.payload);
                 if (state.storageKey) {
-                    localStorage.setItem(state.storageKey, JSON.stringify({ achievements: { metrics: state.metrics, unlockedAchievements: state.unlockedAchievements } }));
+                    localStorage.setItem(state.storageKey, JSON.stringify({ achievements: { metrics: state.metrics, unlockedAchievements: state.unlockedAchievements, previouslyAwardedAchievements: state.previouslyAwardedAchievements } }));
+                }
+            }
+        },
+        markAchievementAsAwarded: (state, action) => {
+            if (!state.previouslyAwardedAchievements.includes(action.payload)) {
+                state.previouslyAwardedAchievements.push(action.payload);
+                if (state.storageKey) {
+                    localStorage.setItem(state.storageKey, JSON.stringify({ achievements: { metrics: state.metrics, unlockedAchievements: state.unlockedAchievements, previouslyAwardedAchievements: state.previouslyAwardedAchievements } }));
                 }
             }
         },
         resetAchievements: (state) => {
             state.metrics = {};
             state.unlockedAchievements = [];
+            state.previouslyAwardedAchievements = [];
             if (state.storageKey) {
                 localStorage.removeItem(state.storageKey);
             }
         },
     },
 });
-const { initialize, setMetrics, unlockAchievement, resetAchievements } = achievementSlice.actions;
+const { initialize, setMetrics, unlockAchievement, resetAchievements, markAchievementAsAwarded } = achievementSlice.actions;
 var achievementSlice$1 = achievementSlice.reducer;
 
 const initialState = {
@@ -2242,6 +2260,7 @@ const AchievementProvider = ({ children, config, initialState = {}, storageKey =
     const dispatch = useDispatch();
     const metrics = useSelector((state) => state.achievements.metrics);
     const unlockedAchievementIds = useSelector((state) => state.achievements.unlockedAchievements);
+    const previouslyAwardedAchievementIds = useSelector((state) => state.achievements.previouslyAwardedAchievements);
     const notifications = useSelector((state) => state.notifications.notifications);
     const mergedStyles = React__default.useMemo(() => mergeDeep(defaultStyles, styles), [styles]);
     const [currentAchievement, setCurrentAchievement] = React__default.useState(null);
@@ -2259,31 +2278,40 @@ const AchievementProvider = ({ children, config, initialState = {}, storageKey =
         dispatch(initialize({ config, initialState, storageKey }));
     }, [dispatch, config, initialState, storageKey]);
     const checkAchievements = useCallback(() => {
-        const newAchievements = [];
+        const newAchievementsToAward = [];
         if (!unlockedAchievementIds) {
             console.error('unlockedAchievements is undefined!');
             return;
         }
-        Object.entries(config).forEach(([metricName, conditions]) => {
+        Object.entries(config)
+            .forEach(([metricName, conditions]) => {
             const metricValues = metrics[metricName];
             if (!metricValues) {
                 return;
             }
-            conditions.forEach((condition) => {
+            conditions
+                .filter(condition => !previouslyAwardedAchievementIds.includes(condition.achievementDetails.achievementId))
+                .forEach((condition) => {
                 if (metricValues.some((value) => condition.isConditionMet(value)) &&
                     !unlockedAchievementIds.includes(condition.achievementDetails.achievementId)) {
-                    newAchievements.push(condition.achievementDetails);
+                    dispatch(unlockAchievement(condition.achievementDetails.achievementId));
+                    newAchievementsToAward.push(condition.achievementDetails);
+                }
+                else if (metricValues.some((value) => condition.isConditionMet(value)) &&
+                    unlockedAchievementIds.includes(condition.achievementDetails.achievementId) &&
+                    !previouslyAwardedAchievementIds.includes(condition.achievementDetails.achievementId)) {
+                    newAchievementsToAward.push(condition.achievementDetails);
                 }
             });
         });
-        if (newAchievements.length > 0) {
-            newAchievements.forEach((achievement) => {
-                dispatch(unlockAchievement(achievement.achievementId));
+        if (newAchievementsToAward.length > 0) {
+            newAchievementsToAward.forEach((achievement) => {
                 dispatch(addNotification(achievement));
+                dispatch(markAchievementAsAwarded(achievement.achievementId));
             });
             setShowConfetti(true);
         }
-    }, [config, metrics, unlockedAchievementIds, dispatch]);
+    }, [config, metrics, unlockedAchievementIds, previouslyAwardedAchievementIds, dispatch]);
     useEffect(() => {
         checkAchievements();
     }, [metrics, checkAchievements]);
@@ -2298,7 +2326,8 @@ const AchievementProvider = ({ children, config, initialState = {}, storageKey =
             .filter((c) => achievedIds.includes(c.achievementDetails.achievementId))
             .map((c) => c.achievementDetails));
     }, [config]);
-    const unlockedAchievementsDetails = getAchievements(unlockedAchievementIds);
+    getAchievements(unlockedAchievementIds);
+    const previouslyAwardedAchievementsDetails = getAchievements(previouslyAwardedAchievementIds);
     return (React__default.createElement(AchievementContext.Provider, { value: { updateMetrics, unlockedAchievements: unlockedAchievementIds, resetStorage } },
         children,
         React__default.createElement(AchievementModal$1, { isOpen: !!currentAchievement, achievement: currentAchievement, onClose: () => {
@@ -2307,8 +2336,8 @@ const AchievementProvider = ({ children, config, initialState = {}, storageKey =
                     dispatch(clearNotifications());
                 }
             }, styles: mergedStyles.achievementModal, icons: mergedIcons }),
-        React__default.createElement(BadgesModal$1, { isOpen: showBadges, achievements: unlockedAchievementsDetails, onClose: () => setShowBadges(false), styles: mergedStyles.badgesModal, icons: mergedIcons }),
-        React__default.createElement(BadgesButton$1, { onClick: showBadgesModal, position: badgesButtonPosition, styles: mergedStyles.badgesButton, unlockedAchievements: unlockedAchievementsDetails }),
+        React__default.createElement(BadgesModal$1, { isOpen: showBadges, achievements: previouslyAwardedAchievementsDetails, onClose: () => setShowBadges(false), styles: mergedStyles.badgesModal, icons: mergedIcons }),
+        React__default.createElement(BadgesButton$1, { onClick: showBadgesModal, position: badgesButtonPosition, styles: mergedStyles.badgesButton, unlockedAchievements: previouslyAwardedAchievementsDetails }),
         React__default.createElement(ConfettiWrapper, { show: showConfetti || notifications.length > 0 })));
 };
 function isObject(item) {
@@ -2334,4 +2363,13 @@ function mergeDeep(target, source) {
     return output;
 }
 
-export { AchievementProvider, ConfettiWrapper, achievementSlice$1 as achievementReducer, notificationSlice$1 as notificationReducer, useAchievementContext as useAchievement };
+const useAchievementState = () => {
+    const metrics = useSelector((state) => state.achievements.metrics);
+    const previouslyAwardedAchievements = useSelector((state) => state.achievements.previouslyAwardedAchievements);
+    return {
+        metrics,
+        previouslyAwardedAchievements,
+    };
+};
+
+export { AchievementProvider, ConfettiWrapper, achievementSlice$1 as achievementReducer, notificationSlice$1 as notificationReducer, useAchievementContext as useAchievement, useAchievementState };

package/dist/redux/achievementSlice.d.ts

@@ -4,22 +4,28 @@ export interface AchievementState {
     config: AchievementConfiguration;
     metrics: AchievementMetrics;
     unlockedAchievements: string[];
+    previouslyAwardedAchievements: string[];
     storageKey: string | null;
 }
 export declare const achievementSlice: import("@reduxjs/toolkit").Slice<AchievementState, {
     initialize: (state: import("immer/dist/internal").WritableDraft<AchievementState>, action: PayloadAction<{
         config: AchievementConfiguration;
-        initialState?: InitialAchievementMetrics;
+        initialState?: InitialAchievementMetrics & {
+            previouslyAwardedAchievements?: string[];
+        };
         storageKey: string;
     }>) => void;
     setMetrics: (state: import("immer/dist/internal").WritableDraft<AchievementState>, action: PayloadAction<AchievementMetrics>) => void;
     unlockAchievement: (state: import("immer/dist/internal").WritableDraft<AchievementState>, action: PayloadAction<string>) => void;
+    markAchievementAsAwarded: (state: import("immer/dist/internal").WritableDraft<AchievementState>, action: PayloadAction<string>) => void;
     resetAchievements: (state: import("immer/dist/internal").WritableDraft<AchievementState>) => void;
 }, "achievements">;
 export declare const initialize: import("@reduxjs/toolkit").ActionCreatorWithPayload<{
     config: AchievementConfiguration;
-    initialState?: InitialAchievementMetrics;
+    initialState?: InitialAchievementMetrics & {
+        previouslyAwardedAchievements?: string[];
+    };
     storageKey: string;
-}, "achievements/initialize">, setMetrics: import("@reduxjs/toolkit").ActionCreatorWithPayload<AchievementMetrics, "achievements/setMetrics">, unlockAchievement: import("@reduxjs/toolkit").ActionCreatorWithPayload<string, "achievements/unlockAchievement">, resetAchievements: import("@reduxjs/toolkit").ActionCreatorWithoutPayload<"achievements/resetAchievements">;
+}, "achievements/initialize">, setMetrics: import("@reduxjs/toolkit").ActionCreatorWithPayload<AchievementMetrics, "achievements/setMetrics">, unlockAchievement: import("@reduxjs/toolkit").ActionCreatorWithPayload<string, "achievements/unlockAchievement">, resetAchievements: import("@reduxjs/toolkit").ActionCreatorWithoutPayload<"achievements/resetAchievements">, markAchievementAsAwarded: import("@reduxjs/toolkit").ActionCreatorWithPayload<string, "achievements/markAchievementAsAwarded">;
 declare const _default: import("@reduxjs/toolkit").Reducer<AchievementState>;
 export default _default;

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import { Styles } from "./defaultStyles";
 export type AchievementMetricValue = number | string | boolean | Date;
 export interface AchievementDetails {
     achievementId: string;
@@ -14,10 +15,12 @@ export type AchievementMetrics = Record<string, AchievementMetricValue[]>;
 export interface AchievementProviderProps {
     children: React.ReactNode;
     config: AchievementConfiguration;
-    initialState?: InitialAchievementMetrics;
+    initialState?: InitialAchievementMetrics & {
+        previouslyAwardedAchievements?: string[];
+    };
     storageKey?: string;
     badgesButtonPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
-    styles?: Partial<import('./defaultStyles').Styles>;
+    styles?: Partial<Styles>;
     icons?: Record<string, string>;
 }
 export interface AchievementUnlockCondition<T extends AchievementMetricValue> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-achievements",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "description": "This package allows users to transpose a React achievements engine over their React apps",
   "keywords": [
     "react",

package/src/hooks/useAchievementState.ts

@@ -0,0 +1,12 @@
+import { useSelector } from 'react-redux';
+import { RootState } from '../redux/store';
+
+export const useAchievementState = () => {
+    const metrics = useSelector((state: RootState) => state.achievements.metrics);
+    const previouslyAwardedAchievements = useSelector((state: RootState) => state.achievements.previouslyAwardedAchievements);
+
+    return {
+        metrics,
+        previouslyAwardedAchievements,
+    };
+};

package/src/index.ts

@@ -3,6 +3,7 @@ import { AchievementMetrics, AchievementConfiguration, AchievementDetails, Achie
 import ConfettiWrapper from './components/ConfettiWrapper';
 import achievementReducer from './redux/achievementSlice';
 import notificationReducer from './redux/notificationSlice'
+import { useAchievementState } from './hooks/useAchievementState';
 
 export {
     AchievementProvider,
@@ -14,4 +15,5 @@ export {
     ConfettiWrapper,
     achievementReducer,
     notificationReducer,
+    useAchievementState,
 };

package/src/providers/AchievementProvider.tsx

@@ -1,7 +1,7 @@
 import React, { useEffect, useCallback } from 'react';
 import { useSelector, useDispatch } from 'react-redux';
 import { RootState, AppDispatch } from '../redux/store';
-import { initialize, setMetrics, unlockAchievement, resetAchievements } from '../redux/achievementSlice';
+import { initialize, setMetrics, unlockAchievement, resetAchievements, markAchievementAsAwarded } from '../redux/achievementSlice';
 import { addNotification, clearNotifications } from '../redux/notificationSlice';
 import {
     AchievementDetails,
@@ -45,6 +45,7 @@ export const AchievementProvider: React.FC<AchievementProviderProps> = ({
     const dispatch: AppDispatch = useDispatch();
     const metrics = useSelector((state: RootState) => state.achievements.metrics);
     const unlockedAchievementIds = useSelector((state: RootState) => state.achievements.unlockedAchievements);
+    const previouslyAwardedAchievementIds = useSelector((state: RootState) => state.achievements.previouslyAwardedAchievements);
     const notifications = useSelector((state: RootState) => state.notifications.notifications);
     const mergedStyles = React.useMemo(() => mergeDeep(defaultStyles, styles), [styles]);
 
@@ -71,38 +72,48 @@ export const AchievementProvider: React.FC<AchievementProviderProps> = ({
     }, [dispatch, config, initialState, storageKey]);
 
     const checkAchievements = useCallback(() => {
-        const newAchievements: AchievementDetails[] = [];
+        const newAchievementsToAward: AchievementDetails[] = [];
 
         if (!unlockedAchievementIds) {
             console.error('unlockedAchievements is undefined!');
             return;
         }
 
-        Object.entries(config).forEach(([metricName, conditions]) => {
-            const metricValues = metrics[metricName];
+        Object.entries(config)
+            .forEach(([metricName, conditions]) => {
+                const metricValues = metrics[metricName];
 
-            if (!metricValues) {
-                return;
-            }
-
-            conditions.forEach((condition) => {
-                if (
-                    metricValues.some((value: AchievementMetricValue) => condition.isConditionMet(value)) &&
-                    !unlockedAchievementIds.includes(condition.achievementDetails.achievementId)
-                ) {
-                    newAchievements.push(condition.achievementDetails);
+                if (!metricValues) {
+                    return;
                 }
+
+                conditions
+                    .filter(condition => !previouslyAwardedAchievementIds.includes(condition.achievementDetails.achievementId))
+                    .forEach((condition) => {
+                        if (
+                            metricValues.some((value: AchievementMetricValue) => condition.isConditionMet(value)) &&
+                            !unlockedAchievementIds.includes(condition.achievementDetails.achievementId)
+                        ) {
+                            dispatch(unlockAchievement(condition.achievementDetails.achievementId));
+                            newAchievementsToAward.push(condition.achievementDetails);
+                        } else if (
+                            metricValues.some((value: AchievementMetricValue) => condition.isConditionMet(value)) &&
+                            unlockedAchievementIds.includes(condition.achievementDetails.achievementId) &&
+                            !previouslyAwardedAchievementIds.includes(condition.achievementDetails.achievementId)
+                        ) {
+                            newAchievementsToAward.push(condition.achievementDetails);
+                        }
+                    });
             });
-        });
 
-        if (newAchievements.length > 0) {
-            newAchievements.forEach((achievement) => {
-                dispatch(unlockAchievement(achievement.achievementId));
+        if (newAchievementsToAward.length > 0) {
+            newAchievementsToAward.forEach((achievement) => {
                 dispatch(addNotification(achievement));
+                dispatch(markAchievementAsAwarded(achievement.achievementId));
             });
             setShowConfetti(true);
         }
-    }, [config, metrics, unlockedAchievementIds, dispatch]);
+    }, [config, metrics, unlockedAchievementIds, previouslyAwardedAchievementIds, dispatch]);
 
     useEffect(() => {
         checkAchievements();
@@ -128,6 +139,7 @@ export const AchievementProvider: React.FC<AchievementProviderProps> = ({
     );
 
     const unlockedAchievementsDetails = getAchievements(unlockedAchievementIds);
+    const previouslyAwardedAchievementsDetails = getAchievements(previouslyAwardedAchievementIds);
 
     return (
         <AchievementContext.Provider value={{ updateMetrics, unlockedAchievements: unlockedAchievementIds, resetStorage }}>
@@ -146,7 +158,7 @@ export const AchievementProvider: React.FC<AchievementProviderProps> = ({
             />
             <BadgesModal
                 isOpen={showBadges}
-                achievements={unlockedAchievementsDetails}
+                achievements={previouslyAwardedAchievementsDetails}
                 onClose={() => setShowBadges(false)}
                 styles={mergedStyles.badgesModal}
                 icons={mergedIcons}
@@ -155,7 +167,7 @@ export const AchievementProvider: React.FC<AchievementProviderProps> = ({
                 onClick={showBadgesModal}
                 position={badgesButtonPosition}
                 styles={mergedStyles.badgesButton}
-                unlockedAchievements={unlockedAchievementsDetails}
+                unlockedAchievements={previouslyAwardedAchievementsDetails}
             />
             <ConfettiWrapper show={showConfetti || notifications.length > 0} />
         </AchievementContext.Provider>
@@ -182,4 +194,4 @@ export function mergeDeep(target: any, source: any) {
         });
     }
     return output;
-}
+}

package/src/redux/achievementSlice.ts

@@ -1,3 +1,4 @@
+// src/redux/achievementSlice.ts
 import { createSlice, PayloadAction } from '@reduxjs/toolkit';
 import {
     AchievementConfiguration,
@@ -9,6 +10,7 @@ export interface AchievementState {
     config: AchievementConfiguration;
     metrics: AchievementMetrics;
     unlockedAchievements: string[];
+    previouslyAwardedAchievements: string[];
     storageKey: string | null;
 }
 
@@ -16,6 +18,7 @@ const initialState: AchievementState = {
     config: {},
     metrics: {},
     unlockedAchievements: [],
+    previouslyAwardedAchievements: [], // Initialize as empty
     storageKey: null,
 };
 
@@ -23,42 +26,61 @@ export const achievementSlice = createSlice({
     name: 'achievements',
     initialState,
     reducers: {
-        initialize: (state, action: PayloadAction<{ config: AchievementConfiguration; initialState?: InitialAchievementMetrics; storageKey: string }>) => {
+        initialize: (state, action: PayloadAction<{ config: AchievementConfiguration; initialState?: InitialAchievementMetrics & { previouslyAwardedAchievements?: string[] }; storageKey: string }>) => {
             state.config = action.payload.config;
             state.storageKey = action.payload.storageKey;
             const storedState = action.payload.storageKey ? localStorage.getItem(action.payload.storageKey) : null;
+
+            const initialMetrics = action.payload.initialState ? Object.keys(action.payload.initialState)
+                .filter(key => key !== 'previouslyAwardedAchievements')
+                .reduce((acc, key) => ({ ...acc, [key]: Array.isArray(action.payload.initialState![key]) ? action.payload.initialState![key] : [action.payload.initialState![key]] }), {}) : {};
+
+            const initialAwarded = action.payload.initialState?.previouslyAwardedAchievements || [];
+
             if (storedState) {
                 try {
                     const parsedState = JSON.parse(storedState);
-                    state.metrics = parsedState.achievements?.metrics || {};
+                    state.metrics = parsedState.achievements?.metrics || initialMetrics;
                     state.unlockedAchievements = parsedState.achievements?.unlockedAchievements || [];
+                    state.previouslyAwardedAchievements = parsedState.achievements?.previouslyAwardedAchievements || initialAwarded; // Prioritize stored, fallback to initial
                 } catch (error) {
                     console.error('Error parsing stored achievement state:', error);
-                    state.metrics = action.payload.initialState ? Object.keys(action.payload.initialState).reduce((acc, key) => ({ ...acc, [key]: Array.isArray(action.payload.initialState![key]) ? action.payload.initialState![key] : [action.payload.initialState![key]] }), {}) : {};
+                    state.metrics = initialMetrics;
                     state.unlockedAchievements = [];
+                    state.previouslyAwardedAchievements = initialAwarded;
                 }
             } else {
-                state.metrics = action.payload.initialState ? Object.keys(action.payload.initialState).reduce((acc, key) => ({ ...acc, [key]: Array.isArray(action.payload.initialState![key]) ? action.payload.initialState![key] : [action.payload.initialState![key]] }), {}) : {};
+                state.metrics = initialMetrics;
                 state.unlockedAchievements = [];
+                state.previouslyAwardedAchievements = initialAwarded;
             }
         },
         setMetrics: (state, action: PayloadAction<AchievementMetrics>) => {
             state.metrics = action.payload;
             if (state.storageKey) {
-                localStorage.setItem(state.storageKey, JSON.stringify({ achievements: { metrics: state.metrics, unlockedAchievements: state.unlockedAchievements } }));
+                localStorage.setItem(state.storageKey, JSON.stringify({ achievements: { metrics: state.metrics, unlockedAchievements: state.unlockedAchievements, previouslyAwardedAchievements: state.previouslyAwardedAchievements } }));
             }
         },
         unlockAchievement: (state, action: PayloadAction<string>) => {
             if (!state.unlockedAchievements.includes(action.payload)) {
                 state.unlockedAchievements.push(action.payload);
                 if (state.storageKey) {
-                    localStorage.setItem(state.storageKey, JSON.stringify({ achievements: { metrics: state.metrics, unlockedAchievements: state.unlockedAchievements } }));
+                    localStorage.setItem(state.storageKey, JSON.stringify({ achievements: { metrics: state.metrics, unlockedAchievements: state.unlockedAchievements, previouslyAwardedAchievements: state.previouslyAwardedAchievements } }));
+                }
+            }
+        },
+        markAchievementAsAwarded: (state, action: PayloadAction<string>) => {
+            if (!state.previouslyAwardedAchievements.includes(action.payload)) {
+                state.previouslyAwardedAchievements.push(action.payload);
+                if (state.storageKey) {
+                    localStorage.setItem(state.storageKey, JSON.stringify({ achievements: { metrics: state.metrics, unlockedAchievements: state.unlockedAchievements, previouslyAwardedAchievements: state.previouslyAwardedAchievements } }));
                 }
             }
         },
         resetAchievements: (state) => {
             state.metrics = {};
             state.unlockedAchievements = [];
+            state.previouslyAwardedAchievements = [];
             if (state.storageKey) {
                 localStorage.removeItem(state.storageKey);
             }
@@ -66,6 +88,6 @@ export const achievementSlice = createSlice({
     },
 });
 
-export const { initialize, setMetrics, unlockAchievement, resetAchievements } = achievementSlice.actions;
+export const { initialize, setMetrics, unlockAchievement, resetAchievements, markAchievementAsAwarded } = achievementSlice.actions;
 
 export default achievementSlice.reducer;

package/src/types.ts

@@ -1,3 +1,5 @@
+import {Styles} from "./defaultStyles";
+
 export type AchievementMetricValue = number | string | boolean | Date;
 
 export interface AchievementDetails {
@@ -19,10 +21,10 @@ export type AchievementMetrics = Record<string, AchievementMetricValue[]>;
 export interface AchievementProviderProps {
     children: React.ReactNode;
     config: AchievementConfiguration;
-    initialState?: InitialAchievementMetrics;
+    initialState?: InitialAchievementMetrics & { previouslyAwardedAchievements?: string[] }; // Add optional previouslyAwardedAchievements
     storageKey?: string;
     badgesButtonPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
-    styles?: Partial<import('./defaultStyles').Styles>;
+    styles?: Partial<Styles>;
     icons?: Record<string, string>;
 }