react-achievements 1.3.0 → 1.3.2

package/README.md

@@ -1,164 +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.
 
-The first thing you need to do is install react-achievements:
+<h2 align="center">🚀 Installation</h2>
 
-`npm install react-achievements`
+Install `react-achievements` using npm or yarn:
 
-or if you're using yarn:
-`yarn add react-achievements`
+```bash
+npm install react-achievements
+```
+
+or
 
-## Usage
+```bash
+yarn add react-achievements
+```
 
-### Set up the AchievementProvider
+<h2 align="center">🎮 Usage</h2>
 
-Wrap your app or a part of your app with the AchievementProvider:
+Let's walk through setting up a simple RPG-style game with achievements using React-Achievements.
 
-```
+<h3 align="center">🛠 Set up the AchievementProvider</h3>
+
+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 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
-      }
-    ]
-}
+export default App;
 ```
 
-### Create an achievement configuration
+<h3 align="center">📝 Create an achievement configuration</h3>
+
 Create a file (e.g., achievementConfig.js) to define your achievements:
-(It is important that your icons be located in the public folder of your project)
+
 ```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,
+      check: (value) => value >= 10,
       data: {
-        id: 'first_transaction',
-        title: 'First Transaction',
-        description: 'Completed your first transaction',
-        icon: image1
+        id: 'level_10',
+        title: 'Novice Adventurer',
+        description: 'Reached level 10',
+        icon: levelUpIcon
       }
     },
     {
-      check: (value) => values.reduce((sum, val) => sum + (typeof val === 'number' ? val : 0), 0) >= 100,
+      check: (value) => value >= 50,
       data: {
-          id: 'thousand_dollars',
-          title: 'Big Spender',
-          description: 'Spent a total of $1000', 
-          icon: image2
+        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
+      }
+    }
   ],
-  // Add more metrics and achievements as needed
+  questsCompleted: [
+    {
+      check: (value) => value >= 50,
+      data: {
+        id: 'quest_master',
+        title: 'Quest Master',
+        description: 'Completed 50 quests',
+        icon: questMasterIcon
+      }
+    }
+  ]
 };
 
 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">
-```
+<h3 align="center">🎣 Use the useAchievement hook</h3>
 
-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
+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();
+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 handleNewTransaction = () => {
-    // Your transaction logic here
-    setMetrics(prevMetrics => ({
-      ...prevMetrics,
-      transactions: (prevMetrics.transactions || 0) + 1
-    }));
+  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}>New Transaction</button>
+    <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
+<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, 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.
 
-### Flexible Achievement System: 
-Define custom metrics and achievement conditions.
+<h2 align="center">🔧 API</h2>
 
-### Automatic Achievement Tracking: 
-Achievements are automatically checked and unlocked when metrics change.
+<h3 align="center">🏗 AchievementProvider</h3>
 
-### Achievement Notifications: 
-A modal pops up when an achievement is unlocked.
+#### Props:
 
-### Persistent Achievements: 
-Achieved achievements are stored in local storage. We have not implemented a feature for this to be permanently stored in a database. But we will.
-Achievements are stored in local storage as:
-1. Key: 'react-achievements-achievements' (This is an array of all the achievements that have been unlocked)
-2. Key: 'react-achievements-metrics' (This is an object of all the metrics that have been updated)
+- `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.
 
-### Achievement Gallery: 
-Users can view all their unlocked achievements.
+<h3 align="center">🪝 useAchievement Hook</h3>
 
-### 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.
+#### Returns an object with:
 
-## API
-### AchievementProvider
-#### Props:
+- `setMetrics`: Function to update the metrics.
+- `metrics`: Current metrics object.
+- `unlockedAchievements`: Array of unlocked achievement IDs.
+- `showBadgesModal`: Function to manually show the badges modal.
+
+<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>
+  );
+}
+```
 
-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'
+### achievementModal
 
-2. useAchievement Hook Returns an object with:
+Customizes the modal that appears when an achievement is unlocked.
 
-3. setMetrics: Function to update the metrics.
+```
+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',
+  },
+}
+```
 
-4. metrics: Current metrics object. 
-5. achievedAchievements: Array of achieved achievement IDs. 
-6. showBadgesModal: Function to manually show the badges modal.
+### badgesModal
 
-Customization
+```
+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
+}
+
+```
 
-You can customize the appearance of the achievement modal, badges modal, and badges button by modifying their respective components in the package.
+This allows you to match the achievement system's look and feel to your game or application's theme.
 
-License MIT
+<h2 align="center">📄 License</h2>
+MIT
 
-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.
+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/dist/components/AchievementModal.d.ts

@@ -1,9 +1,11 @@
 import React from 'react';
 import { AchievementData } from '../types';
+import { Styles } from '../defaultStyles';
 interface AchievementModalProps {
-    show: boolean;
+    isOpen: boolean;
     achievement: AchievementData | null;
     onClose: () => void;
+    styles: Styles['achievementModal'];
 }
 declare const _default: React.NamedExoticComponent<AchievementModalProps>;
 export default _default;

package/dist/components/BadgesButton.d.ts

@@ -1,7 +1,9 @@
 import React from 'react';
+import { Styles } from '../defaultStyles';
 interface BadgesButtonProps {
     onClick: () => void;
     position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    styles: Styles['badgesButton'];
 }
 declare const _default: React.NamedExoticComponent<BadgesButtonProps>;
 export default _default;

package/dist/components/BadgesModal.d.ts

@@ -1,9 +1,11 @@
 import React from 'react';
 import { AchievementData } from '../types';
+import { Styles } from '../defaultStyles';
 interface BadgesModalProps {
-    show: boolean;
+    isOpen: boolean;
     achievements: AchievementData[];
     onClose: () => void;
+    styles: Styles['badgesModal'];
 }
 declare const _default: React.NamedExoticComponent<BadgesModalProps>;
 export default _default;

package/dist/components/ConfettiWrapper.d.ts

@@ -1,8 +1,6 @@
 import React from 'react';
-import { ConfettiProps } from 'react-confetti';
 interface ConfettiWrapperProps {
     show: boolean;
-    confettiProps?: Partial<ConfettiProps>;
 }
 declare const ConfettiWrapper: React.FC<ConfettiWrapperProps>;
 export default ConfettiWrapper;

package/dist/context/AchievementContext.d.ts

@@ -1,5 +1,6 @@
 import React, { ReactNode } from 'react';
 import { Metrics, AchievementConfig, MetricValue } from '../types';
+import { Styles } from '../defaultStyles';
 interface AchievementContextProps {
     metrics: Metrics;
     setMetrics: (metrics: Metrics | ((prevMetrics: Metrics) => Metrics)) => void;
@@ -13,6 +14,7 @@ interface AchievementProviderProps {
     initialState?: Record<string, MetricValue>;
     storageKey?: string;
     badgesButtonPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    styles?: Partial<Styles>;
 }
 export declare const AchievementProvider: React.FC<AchievementProviderProps>;
 export declare const useAchievement: () => AchievementContextProps;

package/dist/defaultStyles.d.ts

@@ -0,0 +1,28 @@
+type StyleObject = {
+    [key: string]: string | number;
+};
+interface ModalStyles {
+    overlay: StyleObject;
+    content: StyleObject;
+    title: StyleObject;
+    icon: StyleObject;
+    description: StyleObject;
+    button: StyleObject;
+}
+interface BadgesModalStyles {
+    overlay: StyleObject;
+    content: StyleObject;
+    title: StyleObject;
+    badgeContainer: StyleObject;
+    badge: StyleObject;
+    badgeIcon: StyleObject;
+    badgeTitle: StyleObject;
+    button: StyleObject;
+}
+export interface Styles {
+    achievementModal: ModalStyles;
+    badgesModal: BadgesModalStyles;
+    badgesButton: StyleObject;
+}
+export declare const defaultStyles: Styles;
+export {};