react-achievements 2.2.2 → 3.0.1

package/README.md

@@ -1,463 +1,439 @@
-<h1 align="center">🏆 React-Achievements 🏆</h1>
+# React Achievements
 
-<p align="center">A flexible and customizable achievement system for React applications, perfect for adding gamification elements to your projects.</p>
+A flexible and extensible achievement system for React applications. This package provides the foundation for implementing achievements in React applications with support for multiple state management solutions including Redux, Zustand, and Context API. Check the `stories/examples` directory for implementation examples with different state management solutions.
 
-![React Achievements Demo](https://media.giphy.com/media/5sXoITml136LmyBPEc/giphy.gif)
+<p align="center">
+  <img src="https://media4.giphy.com/media/v1.Y2lkPTc5MGI3NjExbnMxdHVqanZvbGR6czJqOTdpejZqc3F3NXh6a2FiM3lmdnB0d3VoOSZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/LYXAZelQMeeYpzbgtT/giphy.gif" alt="React Achievements Demo" width="600" />
+</p>
 
-<p align="center">If you want to test the package, you can try it out here:</p>
+## Quick Start
 
-<p align="center">https://stackblitz.com/edit/vitejs-vite-sccdux</p>
+Here's a complete working example that shows automatic notifications and achievement tracking:
 
-<h2 align="center">🚀 Installation</h2>
+```tsx
+import React, { useState } from 'react';
+import { 
+  AchievementProvider, 
+  useAchievements, 
+  BadgesButton, 
+  BadgesModal 
+} from 'react-achievements';
+
+// Define a simple achievement
+const achievementConfig = {
+  score: [{
+    isConditionMet: (value: number) => value >= 100,
+    achievementDetails: {
+      achievementId: 'score_100',
+      achievementTitle: 'Century!',
+      achievementDescription: 'Score 100 points',
+      achievementIconKey: 'trophy'
+    }
+  }]
+};
 
-Install `react-achievements` and its peer dependencies using npm or yarn:
+// Demo component with all essential features
+const DemoComponent = () => {
+  const [isModalOpen, setIsModalOpen] = useState(false);
+  const { update, achievements, reset } = useAchievements();
+
+  return (
+    <div>
+      <h1>Achievement Demo</h1>
+      
+      {/* Button to trigger achievement */}
+      <button onClick={() => update({ score: 100 })}>
+        Score 100 points
+      </button>
+      
+      {/* Reset button */}
+      <button onClick={reset}>
+        Reset Achievements
+      </button>
+      
+      {/* Shows unlocked achievements count */}
+      <p>Unlocked: {achievements.unlocked.length}</p>
+      
+      {/* Floating badges button */}
+      <BadgesButton 
+        position="bottom-right"
+        onClick={() => setIsModalOpen(true)}
+        unlockedAchievements={achievements.unlocked}
+      />
+      
+      {/* Achievement history modal */}
+      <BadgesModal 
+        isOpen={isModalOpen}
+        onClose={() => setIsModalOpen(false)}
+        achievements={achievements.unlocked}
+      />
+    </div>
+  );
+};
 
-```bash
-npm install react-achievements @reduxjs/toolkit react-redux react-toastify react-confetti react-use
+// Root component with provider
+const App = () => {
+  return (
+    <AchievementProvider
+      achievements={achievementConfig}
+      storage="local"
+    >
+      <DemoComponent />
+    </AchievementProvider>
+  );
+};
+
+export default App;
 ```
 
-or
+When you click "Score 100 points":
+1. A toast notification appears
+2. Confetti animation plays
+3. The achievement is stored and visible in the badges modal
+4. The badges button updates to show the new count
 
-```bash
-yarn add react-achievements @reduxjs/toolkit react-redux react-toastify react-confetti react-use
-```
+## State Management Options
 
-<h2 align="center">🎮 Usage</h2>
+This package includes example implementations for different state management solutions in the `stories/examples` directory:
 
-Let's walk through setting up a simple RPG-style game with achievements.
+- **Redux**: For large applications with complex state management needs
+- **Zustand**: For applications needing a lightweight, modern state solution
+- **Context API**: For applications preferring React's built-in solutions
 
-<h3 align="center">🛠 Set up the AchievementProvider</h3>
+See the [examples directory](./stories/examples) for detailed implementations and instructions for each state management solution.
 
-First, wrap your app or a part of your app with the AchievementProvider:
+## Features
 
-```jsx
-import React from 'react';
-import { Provider } from 'react-redux';
-import store from './store';
-import { AchievementProvider } from 'react-achievements';
-import Game from './Game';
-import achievementConfig from './achievementConfig';
+- Framework-agnostic achievement system
+- Customizable storage implementations
+- Built-in local storage support
+- Customizable UI components
+- Toast notifications
+- Confetti animations
+- TypeScript support
 
-const initialState = {
-    level: 1,
-    experience: 0,
-    monstersDefeated: 0,
-    questsCompleted: 0,
-    previouslyAwardedAchievements: ['first_step'], // Optional: Load previously awarded achievements
-};
+## Achievement Notifications & History
 
-function App() {
-    return (
-        <Provider store={store}>
-            <AchievementProvider
-                config={achievementConfig} // Required: your achievement configuration
-                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
-            >
-                <Game />
-            </AchievementProvider>
-        </Provider>
-    );
-}
+The package provides two ways to display achievements to users:
 
-export default App;
+### Automatic Notifications
+When an achievement is unlocked, the system automatically:
+- Shows a toast notification in the top-right corner with the achievement details
+- Plays a confetti animation to celebrate the achievement
+
+These notifications appear immediately when achievements are unlocked and require no additional setup.
+
+### Achievement History
+To allow users to view their achievement history, the package provides two essential components:
+
+1. `BadgesButton`: A floating button that shows the number of unlocked achievements
+```tsx
+<BadgesButton 
+  position="bottom-right" // or "top-right", "top-left", "bottom-left"
+  onClick={() => setIsModalOpen(true)}
+  unlockedAchievements={achievements.unlocked}
+/>
 ```
 
-<h3 align="center">🛠 Set up the Store</h3>
+2. `BadgesModal`: A modal dialog that displays all unlocked achievements with their details
+```tsx
+<BadgesModal 
+  isOpen={isModalOpen}
+  onClose={() => setIsModalOpen(false)}
+  achievements={achievements.unlocked}
+  icons={customIcons} // Optional custom icons
+/>
+```
+
+These components are the recommended way to give users access to their achievement history. While you could build custom UI using the `useAchievements` hook data, these components provide a polished, ready-to-use interface for achievement history.
 
-You need to create a store for you state
+## Installation
+
+```bash
+npm install react-achievements
+```
+
+## Basic Usage
 
 ```tsx
-// src/store.ts
-// src/store.js
+import { AchievementProvider, useAchievements } from 'react-achievements';
+// For specific state management implementations:
+// import { AchievementProvider, useAchievements } from 'react-achievements/redux';
+// import { AchievementProvider, useAchievements } from 'react-achievements/zustand';
+// import { AchievementProvider, useAchievements } from 'react-achievements/context';
+
+// Define your achievements with various data types and conditions
+const achievements = {
+  // Numeric achievements with thresholds
+  score: {
+    100: {
+      title: 'Century!',
+      description: 'Score 100 points',
+      icon: 'trophy'
+    },
+    500: {
+      title: 'Half a Thousand!',
+      description: 'Score 500 points',
+      icon: 'gold',
+      condition: (value) => value >= 500
+    }
+  },
 
-import { configureStore } from '@reduxjs/toolkit';
-import achievementReducer from 'react-achievements/redux/achievementSlice';
-import notificationReducer from 'react-achievements/redux/notificationSlice';
+  // Boolean achievements
+  completedTutorial: {
+    true: {
+      title: 'Tutorial Master',
+      description: 'Complete the tutorial',
+      icon: 'book'
+    }
+  },
 
-const store = configureStore({
-  reducer: {
-    achievements: achievementReducer,
-    notifications: notificationReducer,
+  // String-based achievements
+  characterClass: {
+    'wizard': {
+      title: 'Arcane Scholar',
+      description: 'Choose the wizard class',
+      icon: 'wand'
+    },
+    'warrior': {
+      title: 'Battle Hardened',
+      description: 'Choose the warrior class',
+      icon: 'sword'
+    }
   },
-});
 
-// If you are using JavaScript, you don't need to explicitly export RootState and AppDispatch types.
-export type RootState = ReturnType<typeof store.getState>;
-export type AppDispatch = typeof store.dispatch;
+  // Array-based achievements
+  collectedItems: {
+    ['sword', 'shield', 'potion']: {
+      title: 'Fully Equipped',
+      description: 'Collect all essential items',
+      icon: 'backpack',
+      condition: (items) => ['sword', 'shield', 'potion'].every(item => items.includes(item))
+    }
+  },
+
+  // Object-based achievements
+  playerStats: {
+    { strength: 10, intelligence: 10 }: {
+      title: 'Balanced Warrior',
+      description: 'Achieve balanced stats',
+      icon: 'scale',
+      condition: (stats) => stats.strength === 10 && stats.intelligence === 10
+    }
+  },
+
+  // Time-based achievements
+  playTime: {
+    3600: {
+      title: 'Dedicated Player',
+      description: 'Play for 1 hour',
+      icon: 'clock',
+      condition: (seconds) => seconds >= 3600
+    }
+  },
+
+  // Combination achievements
+  combo: {
+    { score: 1000, level: 5 }: {
+      title: 'Rising Star',
+      description: 'Reach level 5 with 1000 points',
+      icon: 'star',
+      condition: (metrics) => metrics.score >= 1000 && metrics.level >= 5
+    }
+  }
+};
+
+// Create your app component
+const App = () => {
+  return (
+    <AchievementProvider
+      achievements={achievements}
+      storage="local" // or "memory" or custom storage
+    >
+      <Game />
+    </AchievementProvider>
+  );
+};
 
-export default store;
+// Use achievements in your components
+const Game = () => {
+  const { update, achievements } = useAchievements();
+
+  const handleScoreUpdate = (newScore: number) => {
+    update({ score: newScore });
+  };
+
+  return (
+    <div>
+      <h1>Game</h1>
+      <p>Unlocked Achievements: {achievements.unlocked.length}</p>
+      <button onClick={() => handleScoreUpdate(100)}>
+        Score 100 points
+      </button>
+    </div>
+  );
+};
 ```
 
-<h3 align="center">📝 Create an achievement configuration</h3>
+## Default Icons
 
-Create a file (e.g., achievementConfig.js) to define your achievements:
+The package comes with a comprehensive set of default icons that you can use in your achievements. These are available through the `defaultAchievementIcons` export:
 
-```javascript
-// achievementConfig.js
-import levelUpIcon from './icons/level-up.png';
-import monsterSlayerIcon from './icons/monster-slayer.png';
-import questMasterIcon from './icons/quest-master.png';
+```tsx
+import { AchievementProvider, defaultAchievementIcons } from 'react-achievements-core';
 
+// Example achievement configuration using default icons
 const achievementConfig = {
-    level: [
-        {
-            isConditionMet: (value) => value >= 1,
-            achievementDetails: {
-                achievementId: 'level_1',
-                achievementTitle: 'Novice Adventurer',
-                achievementDescription: 'Reached level 1',
-                achievementIconKey: 'levelUpIcon', 
-            },
-        },
-        {
-            isConditionMet: (value) => value >= 5,
-            achievementDetails: {
-                achievementId: 'level_5',
-                achievementTitle: 'Seasoned Warrior',
-                achievementDescription: 'Reached level 5',
-                achievementIconKey: 'levelUpIcon',
-            },
-        },
-    ],
-    monstersDefeated: [
-        {
-            isConditionMet: (value) => value >= 10,
-            achievementDetails: {
-                achievementId: 'monster_slayer',
-                achievementTitle: 'Monster Slayer',
-                achievementDescription: 'Defeated 10 monsters',
-                achievementIconKey: 'monsterSlayerIcon',
-            },
-        },
-    ],
-    questsCompleted: [
-        {
-            isConditionMet: (value) => value >= 1,
-            achievementDetails: {
-                achievementId: 'quest_master',
-                achievementTitle: 'Quest Master',
-                achievementDescription: 'Completed 1 quest',
-                achievementIconKey: 'questMasterIcon',
-            },
-        },
-    ],
+  pageViews: [
+    {
+      isConditionMet: (value) => value >= 5,
+      achievementDetails: {
+        achievementId: 'views-5',
+        achievementTitle: 'Getting Started',
+        achievementDescription: 'Viewed 5 pages',
+        achievementIconKey: 'firstStep' // This will use the 👣 emoji from defaultAchievementIcons
+      }
+    }
+  ]
 };
 
-export default achievementConfig;
+// Create your app component
+const App = () => {
+  return (
+    <AchievementProvider
+      achievements={achievementConfig}
+      // The provider automatically uses defaultAchievementIcons
+    >
+      <Game />
+    </AchievementProvider>
+  );
+};
 ```
 
-<h3 align="center">🎣 Use the useAchievement hook</h3>
+### Custom Icons
 
-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 Game() {
-    const { updateMetrics, metrics } = useAchievement();
-    const [currentQuest, setCurrentQuest] = useState(null);
-
-    const defeatMonster = () => {
-        updateMetrics({
-            monstersDefeated: [(metrics.monstersDefeated?.[0] || 0) + 1],
-            experience: [(metrics.experience?.[0] || 0) + 10],
-            level: [Math.floor(((metrics.experience?.[0] || 0) + 10) / 100) + 1], // Calculate new level
-        });
-    };
-
-    const completeQuest = () => {
-        updateMetrics({
-            questsCompleted: [(metrics.questsCompleted?.[0] || 0) + 1],
-            experience: [(metrics.experience?.[0] || 0) + 50],
-            level: [Math.floor(((metrics.experience?.[0] || 0) + 50) / 100) + 1], // Calculate new level
-        });
-        setCurrentQuest(null);
-    };
-
-    const startQuest = () => {
-        setCurrentQuest("Defeat the Dragon");
-    };
-
-    return (
-        <div>
-            <h1>My RPG Game</h1>
-            <p>Level: {metrics.level?.[0] || 1}</p>
-            <p>Experience: {metrics.experience?.[0] || 0}</p>
-            <p>Monsters Defeated: {metrics.monstersDefeated?.[0] || 0}</p>
-            <p>Quests Completed: {metrics.questsCompleted?.[0] || 0}</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>
-    );
-}
+You can also provide your own custom icons that will override or extend the default ones:
 
-export default Game;
-```
+```tsx
+import { AchievementProvider, defaultAchievementIcons } from 'react-achievements-core';
 
-<h2 align="center">✨ Features</h2>
-
-- Flexible Achievement System: Define custom metrics and achievement conditions for your game or app.
-- Built with TypeScript: Provides strong typing and improved developer experience.
-- Redux-Powered State Management: Leverages Redux for predictable and scalable state management of achievements and metrics.
-- Automatic Achievement Tracking: Achievements are automatically checked and unlocked when metrics change.
-- Achievement Notifications: Uses react-toastify to display notifications when an achievement is unlocked
-- Persistent Achievements: Unlocked achievements and metrics are stored in local storage, allowing players to keep their progress
-- Achievement Gallery: Players can view all their unlocked achievements, encouraging completionism
-- Confetti Effect: A celebratory confetti effect is displayed when an achievement is unlocked, adding to the excitement
-- Local Storage: Achievements are stored locally on the device
-- **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>
-
-<h3 align="center">🏗 AchievementProvider</h3>
-
-#### Props:
-
-- `config` (required): An object defining your metrics and achievements
-- `initialState` (optional): 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. One of: 'top-left', 'top-right', 'bottom-left', 'bottom-right'. Default: 'top-right'
-- `styles` (optional): Custom styles for the badges components (see Customization section below)
-- `icons` (optional): Custom icons to use for achievements. You can use the default icons provided by the library (see Available Icons section) or provide your own. Icons should be a Record<string, string> where the key is the iconKey referenced in your achievement config and the value is the icon string/element.
-
-### Available Default Icons
-
-```javascript
-{
-    // 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: '🛡️',
-}
+// Create custom icons by extending the defaults
+const customIcons = {
+  ...defaultAchievementIcons, // Include all default icons
+  levelUp: '🚀', // Override the default for 'levelUp'
+  myCustomIcon: '💻' // Add a new icon not in the defaults
+};
+
+const App = () => {
+  return (
+    <AchievementProvider
+      achievements={achievementConfig}
+      icons={customIcons} // Pass your custom icons to the provider
+    >
+      <Game />
+    </AchievementProvider>
+  );
+};
 ```
 
-<h2 align="center">🎨 Customization</h2>
+### Available Icons
 
-You can customize the look of the achievement badges by overriding the default styles. Pass a `styles` prop to the `AchievementProvider`:
+The `defaultAchievementIcons` includes icons in these categories:
 
-```javascript
-const customStyles = {
-    badge: {
-        // Your custom styles here
-    },
-    // ...other styles
-};
+- General Progress & Milestones (levelUp, questComplete, etc.)
+- Social & Engagement (shared, liked, etc.)
+- Time & Activity (activeDay, streak, etc.)
+- Creativity & Skill (artist, expert, etc.)
+- Achievement Types (bronze, silver, gold, etc.)
+- Numbers & Counters (one, ten, hundred, etc.)
+- Actions & Interactions (clicked, discovered, etc.)
+- Placeholders (default, loading, error, etc.)
+- Miscellaneous (trophy, star, gem, etc.)
 
-<AchievementProvider
-    config={achievementConfig}
-    initialState={initialState}
-    styles={customStyles}
->
-    <Game />
-</AchievementProvider>
-```
+## Custom Storage
 
-<h2 align="center">🔄 Complex Achievement Conditions</h2>
+You can implement your own storage solution by implementing the `AchievementStorage` interface:
 
-<h3 align="center">Achievement Dependencies</h3>
+```typescript
+import { AchievementStorage } from 'react-achievements-core';
 
-You can create achievements that depend on other achievements being unlocked first:
+class CustomStorage implements AchievementStorage {
+  getMetrics() {
+    // Your implementation
+  }
 
-```javascript
-const achievementConfig = {
-    prerequisite: [
-        {
-            isConditionMet: (value) => value === true,
-            achievementDetails: {
-                achievementId: 'prerequisite',
-                achievementTitle: 'Prerequisites Met',
-                achievementDescription: 'Unlocked advanced achievements',
-                achievementIconKey: 'unlock'
-            }
-        }
-    ],
-    dependent: [
-        {
-            isConditionMet: (value, state) => {
-                const prereqMet = state.unlockedAchievements.includes('prerequisite');
-                return prereqMet && typeof value === 'number' && value >= 100;
-            },
-            achievementDetails: {
-                achievementId: 'dependent',
-                achievementTitle: 'Advanced Achievement',
-                achievementDescription: 'Completed an advanced challenge',
-                achievementIconKey: 'star'
-            }
-        }
-    ]
-};
-```
+  setMetrics(metrics) {
+    // Your implementation
+  }
 
-<h3 align="center">Time-Based Achievements</h3>
+  getUnlockedAchievements() {
+    // Your implementation
+  }
 
-You can create achievements based on specific times or dates:
+  setUnlockedAchievements(achievements) {
+    // Your implementation
+  }
 
-```javascript
-const achievementConfig = {
-    loginTime: [
-        {
-            isConditionMet: (value) => {
-                if (!(value instanceof Date)) return false;
-                const hour = value.getHours();
-                return hour >= 22 || hour < 6;
-            },
-            achievementDetails: {
-                achievementId: 'night_owl',
-                achievementTitle: 'Night Owl',
-                achievementDescription: 'Logged in during night hours',
-                achievementIconKey: 'moon'
-            }
-        }
-    ]
+  clear() {
+    // Your implementation
+  }
+}
+
+// Use your custom storage
+const App = () => {
+  return (
+    <AchievementProvider
+      achievements={achievements}
+      storage={new CustomStorage()}
+    >
+      <Game />
+    </AchievementProvider>
+  );
 };
 ```
 
-<h3 align="center">Progressive Achievements</h3>
+## Styling
 
-You can create achievement chains that unlock in sequence:
+You can customize the appearance of the achievement components:
 
-```javascript
-const achievementConfig = {
-    skillLevel: [
-        {
-            isConditionMet: (value) => typeof value === 'number' && value >= 1,
-            achievementDetails: {
-                achievementId: 'skill_novice',
-                achievementTitle: 'Novice',
-                achievementDescription: 'Reached skill level 1',
-                achievementIconKey: 'bronze'
-            }
+```tsx
+const App = () => {
+  return (
+    <AchievementProvider
+      achievements={achievements}
+      theme={{
+        colors: {
+          primary: '#ff0000',
+          background: '#f0f0f0'
         },
-        {
-            isConditionMet: (value) => typeof value === 'number' && value >= 5,
-            achievementDetails: {
-                achievementId: 'skill_master',
-                achievementTitle: 'Master',
-                achievementDescription: 'Reached skill level 5',
-                achievementIconKey: 'gold'
-            }
-        }
-    ]
+        position: 'top-right'
+      }}
+    >
+      <Game />
+    </AchievementProvider>
+  );
 };
 ```
 
-<h2 align="center">💾 Saving and Loading Progress</h2>
-
-To persist user achievement progress across sessions or devices, you can save the metrics and previouslyAwardedAchievements from your Redux store:
-
-```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 {
-            await fetch('/api/save-achievements', {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                },
-                body: JSON.stringify(achievementData),
-            });
-            onLogout();
-        } catch (error) {
-            console.error('Failed to save achievements:', error);
-        }
-    };
-
-    return <button onClick={handleLogoutAndSave}>Logout</button>;
-};
-```
+## API Reference
+
+### AchievementProvider Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| achievements | AchievementConfig | Achievement configuration object |
+| storage | 'local' \| 'memory' \| AchievementStorage | Storage implementation |
+| theme | ThemeConfig | Custom theme configuration |
+| onUnlock | (achievement: Achievement) => void | Callback when achievement is unlocked |
+
+### useAchievements Hook
+
+Returns an object with:
+
+- `update`: Function to update achievement metrics
+- `achievements`: Object containing unlocked and locked achievements
+- `reset`: Function to reset achievement storage
+
+## License
+
+MIT