react-achievements 1.3.1 → 1.3.2

package/README.md

@@ -1,161 +1,371 @@
-# Welcome to React-Achievements!
+Certainly! I'll provide you with a revised version of the README that removes the artifacts-related content. Here's the updated version without the artifacts:
+<h1 align="center">🏆 React-Achievements 🏆</h1>
 
-A flexible and customizable achievement system for React applications.
 
-## Installation
+A flexible and customizable achievement system for React applications, perfect for adding gamification elements to your projects.
 
-Install react-achievements using npm or yarn:
+<h2 align="center">🚀 Installation</h2>
 
-`npm install react-achievements`
+Install `react-achievements` using npm or yarn:
 
+```bash
+npm install react-achievements
+```
+
+or
 
-`yarn add react-achievements`
+```bash
+yarn add react-achievements
+```
 
-## Usage
+<h2 align="center">🎮 Usage</h2>
 
-### Set up the AchievementProvider
+Let's walk through setting up a simple RPG-style game with achievements using React-Achievements.
 
-Wrap your app or a part of your app with the AchievementProvider:
+<h3 align="center">🛠 Set up the AchievementProvider</h3>
 
-```javscript
+First, wrap your app or a part of your app with the AchievementProvider:
+
+```jsx
+import React from 'react';
 import { AchievementProvider } from 'react-achievements';
 import achievementConfig from './achievementConfig';
+import Game from './Game';
+
+const initialState = {
+  level: 1,
+  experience: 0,
+  monstersDefeated: 0,
+  questsCompleted: 0
+};
 
 function App() {
   return (
-    <AchievementProvider config={achievementConfig} initialState={<your_object>}>
-      {/* Your app components */}
+    <AchievementProvider 
+      config={achievementConfig} 
+      initialState={initialState}
+      badgesButtonPosition="top-right"
+    >
+      <Game />
     </AchievementProvider>
   );
 }
-```
-
-The `initialState` prop should contain the current state of your metrics. For example:
 
-```javascript
-const initialState = {
-    transactions: [
-        { id: 1, amount: 100 },
-        { id: 2, amount: 200 }
-    ]
-};
+export default App;
 ```
 
-### Create an achievement configuration
-
-Create a file (e.g., `achievementConfig.js`) to define your achievements:
+<h3 align="center">📝 Create an achievement configuration</h3>
 
+Create a file (e.g., achievementConfig.js) to define your achievements:
 
 ```javascript
-
-
-import image1 from './public/path/to/image1.png';
-import image2 from './public/path/to/image2.png';
+import levelUpIcon from './icons/level-up.png';
+import monsterSlayerIcon from './icons/monster-slayer.png';
+import questMasterIcon from './icons/quest-master.png';
 
 const achievementConfig = {
-transactions: [
+  level: [
     {
-        check: (value) => value.length >= 1,
-        data: {
-            id: 'first_transaction',
-            title: 'First Transaction',
-            description: 'Completed your first transaction',
-            icon: image1
-        }
+      check: (value) => value >= 10,
+      data: {
+        id: 'level_10',
+        title: 'Novice Adventurer',
+        description: 'Reached level 10',
+        icon: levelUpIcon
+      }
     },
     {
-        check: (value) => value.reduce((sum, transaction) => sum + transaction.amount, 0) >= 1000,
-        data: {
-            id: 'thousand_dollars',
-            title: 'Big Spender',
-            description: 'Spent a total of $1000',
-            icon: image2
-        }
-    },
-    ],
-// Add more metrics and achievements as needed, but keys (in this case transactions) must match with those in initialState variable
+      check: (value) => value >= 50,
+      data: {
+        id: 'level_50',
+        title: 'Seasoned Warrior',
+        description: 'Reached level 50',
+        icon: levelUpIcon
+      }
+    }
+  ],
+  monstersDefeated: [
+    {
+      check: (value) => value >= 100,
+      data: {
+        id: 'monster_slayer',
+        title: 'Monster Slayer',
+        description: 'Defeated 100 monsters',
+        icon: monsterSlayerIcon
+      }
+    }
+  ],
+  questsCompleted: [
+    {
+      check: (value) => value >= 50,
+      data: {
+        id: 'quest_master',
+        title: 'Quest Master',
+        description: 'Completed 50 quests',
+        icon: questMasterIcon
+      }
+    }
+  ]
 };
-```
 
 export default achievementConfig;
-
-Note: Ensure your icons are located in the public folder of your project.
-
-### Customize the badges button location
-
-```javascript
-<AchievementProvider
-    config={achievementConfig}
-    badgesButtonPosition="bottom-right"
->
-    {/* Your app components */}
-</AchievementProvider>
 ```
-Specify the position of the badges button:
-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:
+<h3 align="center">🎣 Use the useAchievement hook</h3>
 
-```javascript
+In your game components, use the useAchievement hook to update metrics and trigger achievement checks:
+```jsx
+import React, { useState } from 'react';
 import { useAchievement } from 'react-achievements';
 
-function TransactionComponent() {
-    const { setMetrics } = useAchievement();
-    
-    const handleNewTransaction = (amount) => {
-        setMetrics(prevMetrics => (
-            {
-            ...prevMetrics,
-            transactions: [
-    ...prevMetrics.transactions,
-    { id: Date.now(), amount }
-    ]
-    }));
-};
+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 (
-        <button onClick={() => handleNewTransaction(100)}>New Transaction</button>
-    );
+  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;
 ```
-## Features
 
-- Flexible Achievement System: Define custom metrics and achievement conditions.
+<h2 align="center">✨ Features</h2>
+
+- Flexible Achievement System: Define custom metrics and achievement conditions for your game or app.
 - 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: Unlocked achievements and metrics are stored in local storage.
-- Achievement Gallery: Users can view all their unlocked achievements.
-- Confetti Effect: A celebratory confetti effect is displayed when an achievement is unlocked.
+- 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.
 
-## API
+<h2 align="center">🔧 API</h2>
 
-### AchievementProvider
+<h3 align="center">🏗 AchievementProvider</h3>
 
 #### Props:
+
 - `config`: An object defining your metrics and achievements.
 - `initialState`: The initial state of your metrics.
 - `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.
 
-### useAchievement Hook
+<h3 align="center">🪝 useAchievement Hook</h3>
+
+#### Returns an object with:
 
-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.
 
-## License
+<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`:
+
+```jsx
+const customStyles = {
+  achievementModal: {
+    overlay: {
+      backgroundColor: 'rgba(0, 0, 0, 0.8)',
+    },
+    content: {
+      backgroundColor: '#2a2a2a',
+      color: '#ffffff',
+    },
+    title: {
+      color: '#ffd700',
+    },
+    button: {
+      backgroundColor: '#4CAF50',
+    },
+  },
+  badgesModal: {
+    // Custom styles for the badges modal
+  },
+  badgesButton: {
+    // Custom styles for the badges button
+  },
+};
+
+function App() {
+  return (
+    <AchievementProvider 
+      config={achievementConfig} 
+      initialState={initialState}
+      styles={customStyles}
+    >
+      <Game />
+    </AchievementProvider>
+  );
+}
+```
+
+### achievementModal
+
+Customizes the modal that appears when an achievement is unlocked.
+
+```
+achievementModal: {
+  overlay: {
+    // Styles for the modal overlay (background)
+    backgroundColor: 'rgba(0, 0, 0, 0.8)',
+    // You can also customize other overlay properties like zIndex, transition, etc.
+  },
+  content: {
+    // Styles for the modal content container
+    backgroundColor: '#2a2a2a',
+    color: '#ffffff',
+    borderRadius: '10px',
+    padding: '20px',
+    // Add any other CSS properties for the content container
+  },
+  title: {
+    // Styles for the achievement title
+    fontSize: '24px',
+    fontWeight: 'bold',
+    color: '#ffd700',
+  },
+  icon: {
+    // Styles for the achievement icon
+    width: '64px',
+    height: '64px',
+    marginBottom: '10px',
+  },
+  description: {
+    // Styles for the achievement description
+    fontSize: '16px',
+    marginTop: '10px',
+  },
+  button: {
+    // Styles for the close button
+    backgroundColor: '#4CAF50',
+    color: 'white',
+    padding: '10px 20px',
+    border: 'none',
+    borderRadius: '5px',
+    cursor: 'pointer',
+  },
+}
+```
+
+### badgesModal
+
+```
+badgesModal: {
+  overlay: {
+    // Similar to achievementModal overlay
+  },
+  content: {
+    // Similar to achievementModal content
+  },
+  title: {
+    // Styles for the modal title
+  },
+  badgeContainer: {
+    // Styles for the container holding all badges
+    display: 'flex',
+    flexWrap: 'wrap',
+    justifyContent: 'center',
+  },
+  badge: {
+    // Styles for individual badge containers
+    margin: '10px',
+    textAlign: 'center',
+  },
+  badgeIcon: {
+    // Styles for badge icons
+    width: '50px',
+    height: '50px',
+  },
+  badgeTitle: {
+    // Styles for badge titles
+    fontSize: '14px',
+    marginTop: '5px',
+  },
+  button: {
+    // Styles for the close button (similar to achievementModal button)
+  },
+}
+```
+
+
+### badgesButton
+
+```
+badgesButton: {
+  // Styles for the floating badges button
+  position: 'fixed',
+  padding: '10px 20px',
+  backgroundColor: '#007bff',
+  color: '#ffffff',
+  border: 'none',
+  borderRadius: '5px',
+  cursor: 'pointer',
+  zIndex: 1000,
+  // You can add more CSS properties as needed. These are just regular CSS
+}
+
+```
+
+This allows you to match the achievement system's look and feel to your game or application's theme.
 
+<h2 align="center">📄 License</h2>
 MIT
 
-This package provides a comprehensive achievement system for React applications. It's designed to be flexible, customizable, and easy to integrate into existing projects.
+React-Achievements provides a comprehensive achievement system for React applications, perfect for adding gamification elements to your projects. Whether you're building a game, an educational app, or any interactive experience, this package offers an easy way to implement and manage achievements, enhancing user engagement and retention.

package/package.json

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