react-achievements 1.0.4 → 1.0.6

package/README.md

@@ -0,0 +1,156 @@
+# Welcome to React-Achievements!
+
+A flexible and customizable achievement system for React applications.
+
+## Installation
+
+The first thing you need to do is install react-achievements:
+
+`npm install react-achievements`
+
+or if you're using yarn:
+`yarn add react-achievements`
+
+## Usage
+
+### Set up the AchievementProvider
+
+Wrap your app or a part of your app with the AchievementProvider:
+
+```
+import { AchievementProvider } from 'react-achievements';
+import achievementConfig from './achievementConfig';
+
+function App() {
+  return (
+    <AchievementProvider config={achievementConfig} initialState={<your_object>}>
+      {/* Your app components */}
+    </AchievementProvider>
+  );
+}
+```
+
+The object that you pass to the initialState prop should have keys that match the metrics defined in your achievement configuration. For example, if your achievement configuration defines a 'transactions' metric, your initialState object should look like this:
+```typescript
+const user = {
+    transactions: [
+        {
+            id: 1,
+            amount: 100
+        }, 
+      {
+          id: 2,
+          amount: 200
+      }
+    ]
+}
+```
+
+### Create an achievement configuration
+Create a file (e.g., achievementConfig.js) to define your achievements:
+```javascript
+const achievementConfig = {
+  transactions: [
+    {
+      check: (value) => value.length >= 1,
+      data: {
+        id: 'first_transaction',
+        title: 'First Transaction',
+        description: 'Completed your first transaction',
+        icon: '/path/to/icon.png'
+      }
+    },
+    {
+      check: (value) => value.length >= 10,
+      data: {
+        id: 'ten_transactions',
+        title: 'Ten Transactions',
+        description: 'Completed ten transactions',
+        icon: '/path/to/icon.png'
+      }
+    },
+  ],
+  // Add more metrics and achievements as needed
+};
+
+export default achievementConfig;
+```
+
+### Update the location of the badges button
+You can specify the position of the badges button by passing
+badgesButtonPosition to the AchievementProvider:
+```javascript
+<AchievementProvider config={achievementConfig} badgesButtonPosition="bottom-right">
+```
+
+The possible values for badgesButtonPosition are 
+- `'top-left'`
+- `'top-right'`
+- `'bottom-left'`
+- `'bottom-right'`
+
+###  Use the useAchievement hook
+In your components, use the useAchievement hook to update metrics and trigger achievement checks:
+```javascript
+import { useAchievement } from 'react-achievements';
+
+function TransactionComponent() {
+  const { setMetrics } = useAchievement();
+
+  const handleNewTransaction = () => {
+    // Your transaction logic here
+    setMetrics(prevMetrics => ({
+      ...prevMetrics,
+      transactions: (prevMetrics.transactions || 0) + 1
+    }));
+  };
+
+  return (
+    <button onClick={handleNewTransaction}>New Transaction</button>
+  );
+}
+```
+
+## Features
+
+### Flexible Achievement System: 
+Define custom metrics and achievement conditions.
+
+### Automatic Achievement Tracking: 
+Achievements are automatically checked and unlocked when metrics change.
+
+### Achievement Notifications: 
+A modal pops up when an achievement is unlocked.
+
+### Persistent Achievements: 
+Achieved achievements are stored in local storage.
+
+### Achievement Gallery: 
+Users can view all their unlocked achievements.
+
+### Customizable UI: 
+The achievement modal and badges button can be styled to fit your app's design.
+Confetti Effect: A celebratory confetti effect is displayed when an achievement is unlocked.
+
+## API
+### AchievementProvider
+#### Props:
+
+1. config: An object defining your metrics and achievements.
+storageKey (optional): A string to use as the key for localStorage. Default: 'react-achievements'
+badgesButtonPosition (optional): Position of the badges button. Options: 'top-left', 'top-right', 'bottom-left', 'bottom-right'. Default: 'top-right'
+
+2. useAchievement Hook Returns an object with:
+
+3. setMetrics: Function to update the metrics.
+
+4. metrics: Current metrics object. 
+5. achievedAchievements: Array of achieved achievement IDs. 
+6. showBadgesModal: Function to manually show the badges modal.
+
+Customization
+You can customize the appearance of the achievement modal, badges modal, and badges button by modifying their respective components in the package.
+License
+MIT
+Copy
+This README provides a comprehensive overview of how to use the react-achievements package, including setup, usage examples, features, and API details. You may want to adjust or expand certain sections based on the specific implementation details or additional features of your package.

package/dist/context/AchievementContext.d.ts

@@ -2,7 +2,7 @@ import React, { ReactNode } from 'react';
 import { Metrics, AchievementConfig } from '../types';
 interface AchievementContextProps {
     metrics: Metrics;
-    setMetrics: (metrics: Metrics) => void;
+    setMetrics: (metrics: Metrics | ((prevMetrics: Metrics) => Metrics)) => void;
     achievedAchievements: string[];
     checkAchievements: () => void;
     showBadgesModal: () => void;
@@ -10,6 +10,7 @@ interface AchievementContextProps {
 interface AchievementProviderProps {
     children: ReactNode;
     config: AchievementConfig;
+    initialState?: Record<string, any>;
     storageKey?: string;
     badgesButtonPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
 }

package/dist/index.cjs.js

@@ -185,8 +185,22 @@ const ConfettiWrapper = ({ show, confettiProps }) => {
 };
 
 const AchievementContext = React.createContext(undefined);
-const AchievementProvider = ({ children, config, storageKey = 'react-achievements', badgesButtonPosition = 'top-right' }) => {
-    const [metrics, setMetrics] = React.useState({});
+const AchievementProvider = ({ children, config, initialState = {}, storageKey = 'react-achievements', badgesButtonPosition = 'top-right' }) => {
+    const extractMetrics = (state) => {
+        return Object.keys(config).reduce((acc, key) => {
+            if (key in state) {
+                acc[key] = state[key];
+            }
+            return acc;
+        }, {});
+    };
+    const [metrics, setMetrics] = React.useState(() => {
+        const savedMetrics = localStorage.getItem(`${storageKey}-metrics`);
+        if (savedMetrics) {
+            return JSON.parse(savedMetrics);
+        }
+        return extractMetrics(initialState);
+    });
     const [achievedAchievements, setAchievedAchievements] = React.useState(() => {
         const saved = localStorage.getItem(`${storageKey}-achievements`);
         return saved ? JSON.parse(saved) : [];
@@ -194,7 +208,10 @@ const AchievementProvider = ({ children, config, storageKey = 'react-achievement
     const [newAchievement, setNewAchievement] = React.useState(null);
     const [showBadges, setShowBadges] = React.useState(false);
     const [showConfetti, setShowConfetti] = React.useState(false);
-    const checkAchievements = () => {
+    React.useEffect(() => {
+        localStorage.setItem(`${storageKey}-metrics`, JSON.stringify(metrics));
+    }, [metrics, storageKey]);
+    const checkAchievements = React.useCallback(() => {
         const newAchievements = [];
         Object.entries(config).forEach(([metricKey, conditions]) => {
             const metricValue = metrics[metricKey];
@@ -211,15 +228,20 @@ const AchievementProvider = ({ children, config, storageKey = 'react-achievement
             setNewAchievement(newAchievements[0]);
             setShowConfetti(true);
         }
-    };
+    }, [config, metrics, achievedAchievements, storageKey]);
+    React.useEffect(() => {
+        checkAchievements();
+    }, [checkAchievements]);
     const showBadgesModal = () => {
         setShowBadges(true);
     };
     const contextValue = {
         metrics,
         setMetrics: (newMetrics) => {
-            setMetrics(newMetrics);
-            checkAchievements();
+            setMetrics(prevMetrics => {
+                const updatedMetrics = typeof newMetrics === 'function' ? newMetrics(prevMetrics) : newMetrics;
+                return updatedMetrics;
+            });
         },
         achievedAchievements,
         checkAchievements,

package/dist/index.esm.js

@@ -183,8 +183,22 @@ const ConfettiWrapper = ({ show, confettiProps }) => {
 };
 
 const AchievementContext = createContext(undefined);
-const AchievementProvider = ({ children, config, storageKey = 'react-achievements', badgesButtonPosition = 'top-right' }) => {
-    const [metrics, setMetrics] = useState({});
+const AchievementProvider = ({ children, config, initialState = {}, storageKey = 'react-achievements', badgesButtonPosition = 'top-right' }) => {
+    const extractMetrics = (state) => {
+        return Object.keys(config).reduce((acc, key) => {
+            if (key in state) {
+                acc[key] = state[key];
+            }
+            return acc;
+        }, {});
+    };
+    const [metrics, setMetrics] = useState(() => {
+        const savedMetrics = localStorage.getItem(`${storageKey}-metrics`);
+        if (savedMetrics) {
+            return JSON.parse(savedMetrics);
+        }
+        return extractMetrics(initialState);
+    });
     const [achievedAchievements, setAchievedAchievements] = useState(() => {
         const saved = localStorage.getItem(`${storageKey}-achievements`);
         return saved ? JSON.parse(saved) : [];
@@ -192,7 +206,10 @@ const AchievementProvider = ({ children, config, storageKey = 'react-achievement
     const [newAchievement, setNewAchievement] = useState(null);
     const [showBadges, setShowBadges] = useState(false);
     const [showConfetti, setShowConfetti] = useState(false);
-    const checkAchievements = () => {
+    useEffect(() => {
+        localStorage.setItem(`${storageKey}-metrics`, JSON.stringify(metrics));
+    }, [metrics, storageKey]);
+    const checkAchievements = useCallback(() => {
         const newAchievements = [];
         Object.entries(config).forEach(([metricKey, conditions]) => {
             const metricValue = metrics[metricKey];
@@ -209,15 +226,20 @@ const AchievementProvider = ({ children, config, storageKey = 'react-achievement
             setNewAchievement(newAchievements[0]);
             setShowConfetti(true);
         }
-    };
+    }, [config, metrics, achievedAchievements, storageKey]);
+    useEffect(() => {
+        checkAchievements();
+    }, [checkAchievements]);
     const showBadgesModal = () => {
         setShowBadges(true);
     };
     const contextValue = {
         metrics,
         setMetrics: (newMetrics) => {
-            setMetrics(newMetrics);
-            checkAchievements();
+            setMetrics(prevMetrics => {
+                const updatedMetrics = typeof newMetrics === 'function' ? newMetrics(prevMetrics) : newMetrics;
+                return updatedMetrics;
+            });
         },
         achievedAchievements,
         checkAchievements,

package/package.json

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

package/src/context/AchievementContext.tsx

@@ -1,4 +1,4 @@
-import React, { createContext, useContext, useState, ReactNode } from 'react';
+import React, { createContext, useContext, useState, useEffect, useCallback, ReactNode } from 'react';
 import { Metrics, AchievementConfig, AchievementData } from '../types';
 import AchievementModal from '../components/AchievementModal';
 import BadgesModal from '../components/BadgesModal';
@@ -7,7 +7,7 @@ import ConfettiWrapper from '../components/ConfettiWrapper';
 
 interface AchievementContextProps {
     metrics: Metrics;
-    setMetrics: (metrics: Metrics) => void;
+    setMetrics: (metrics: Metrics | ((prevMetrics: Metrics) => Metrics)) => void;
     achievedAchievements: string[];
     checkAchievements: () => void;
     showBadgesModal: () => void;
@@ -16,6 +16,7 @@ interface AchievementContextProps {
 interface AchievementProviderProps {
     children: ReactNode;
     config: AchievementConfig;
+    initialState?: Record<string, any>;
     storageKey?: string;
     badgesButtonPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
 }
@@ -25,19 +26,41 @@ const AchievementContext = createContext<AchievementContextProps | undefined>(un
 export const AchievementProvider: React.FC<AchievementProviderProps> = ({
                                                                             children,
                                                                             config,
+                                                                            initialState = {},
                                                                             storageKey = 'react-achievements',
                                                                             badgesButtonPosition = 'top-right'
                                                                         }) => {
-    const [metrics, setMetrics] = useState<Metrics>({});
+    const extractMetrics = (state: Record<string, any>): Metrics => {
+        return Object.keys(config).reduce((acc, key) => {
+            if (key in state) {
+                acc[key] = state[key];
+            }
+            return acc;
+        }, {} as Metrics);
+    };
+
+    const [metrics, setMetrics] = useState<Metrics>(() => {
+        const savedMetrics = localStorage.getItem(`${storageKey}-metrics`);
+        if (savedMetrics) {
+            return JSON.parse(savedMetrics);
+        }
+        return extractMetrics(initialState);
+    });
+
     const [achievedAchievements, setAchievedAchievements] = useState<string[]>(() => {
         const saved = localStorage.getItem(`${storageKey}-achievements`);
         return saved ? JSON.parse(saved) : [];
     });
+
     const [newAchievement, setNewAchievement] = useState<AchievementData | null>(null);
     const [showBadges, setShowBadges] = useState(false);
     const [showConfetti, setShowConfetti] = useState(false);
 
-    const checkAchievements = () => {
+    useEffect(() => {
+        localStorage.setItem(`${storageKey}-metrics`, JSON.stringify(metrics));
+    }, [metrics, storageKey]);
+
+    const checkAchievements = useCallback(() => {
         const newAchievements: AchievementData[] = [];
 
         Object.entries(config).forEach(([metricKey, conditions]) => {
@@ -56,7 +79,11 @@ export const AchievementProvider: React.FC<AchievementProviderProps> = ({
             setNewAchievement(newAchievements[0]);
             setShowConfetti(true);
         }
-    };
+    }, [config, metrics, achievedAchievements, storageKey]);
+
+    useEffect(() => {
+        checkAchievements();
+    }, [checkAchievements]);
 
     const showBadgesModal = () => {
         setShowBadges(true);
@@ -64,9 +91,11 @@ export const AchievementProvider: React.FC<AchievementProviderProps> = ({
 
     const contextValue: AchievementContextProps = {
         metrics,
-        setMetrics: (newMetrics: Metrics) => {
-            setMetrics(newMetrics);
-            checkAchievements();
+        setMetrics: (newMetrics) => {
+            setMetrics(prevMetrics => {
+                const updatedMetrics = typeof newMetrics === 'function' ? newMetrics(prevMetrics) : newMetrics;
+                return updatedMetrics;
+            });
         },
         achievedAchievements,
         checkAchievements,

package/public/badges/icon1.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#e8eaed"><path d="M560-440q-50 0-85-35t-35-85q0-50 35-85t85-35q50 0 85 35t35 85q0 50-35 85t-85 35ZM280-320q-33 0-56.5-23.5T200-400v-320q0-33 23.5-56.5T280-800h560q33 0 56.5 23.5T920-720v320q0 33-23.5 56.5T840-320H280Zm80-80h400q0-33 23.5-56.5T840-480v-160q-33 0-56.5-23.5T760-720H360q0 33-23.5 56.5T280-640v160q33 0 56.5 23.5T360-400Zm440 240H120q-33 0-56.5-23.5T40-240v-440h80v440h680v80ZM280-400v-320 320Z"/></svg>