react-achievements 3.5.0 → 3.6.1

package/README.md

@@ -2,17 +2,35 @@
 
 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.
 
-<p align="center">
-  <img src="https://media4.giphy.com/media/v1.Y2lkPTc5MGI3NjExbnMxdHVqanZvbGR6czJqOTdpejZqc3F3NXh6a2FiM3lmdnB0d3VoOSZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/LYXAZelQMeeYpzbgtT/giphy.gif" alt="React Achievements Demo" width="600" />
-</p>
+https://github.com/user-attachments/assets/a33fdae5-439b-4fc9-a388-ccb2f432a3a8
 
 ## Installation
 
+**NEW in v3.6.0**: Optional built-in UI system available! Choose between the traditional external dependencies or the new lightweight built-in UI.
+
+### Option 1: Traditional External UI (Default)
+```bash
+npm install react-achievements react-confetti react-modal react-toastify react-use
+```
+
+### Option 2: Built-in UI (NEW - Opt-in)
 ```bash
-npm install react-achievements react react-dom react-confetti react-modal react-toastify react-use
+npm install react-achievements
+```
+
+Then explicitly enable built-in UI in your code:
+```tsx
+<AchievementProvider
+  achievements={config}
+  useBuiltInUI={true}  // Required to use built-in UI
+>
+  <YourApp />
+</AchievementProvider>
 ```
 
-Note: React and React DOM should be version 16.8.0 or higher. If you already have some of these packages installed, npm will skip them automatically.
+**Requirements**: React 16.8+ and react-dom are required (defined as peerDependencies).
+
+**Note**: To maintain backwards compatibility, v3.6.0 defaults to external UI dependencies. The built-in UI system is opt-in via the `useBuiltInUI` prop. In v4.0.0, built-in UI will become the default. See the [Built-in UI System](#built-in-ui-system-new-in-v360) section below.
 
 ## Quick Start
 
@@ -27,26 +45,40 @@ import {
   BadgesModal 
 } from 'react-achievements';
 
-// Define achievements with the new three-tier Builder API - 95% less code!
+// Define achievements with the Builder API for easy configuration
 import { AchievementBuilder } from 'react-achievements';
 
-// Simple achievements with the new Simple API
-const gameAchievements = {
-  score: {
-    100: { title: 'Century!', description: 'Score 100 points', icon: '🏆' },
-    500: { title: 'High Scorer!', description: 'Score 500 points', icon: '⭐' }
-  },
-  level: {
-    5: { title: 'Leveling Up', description: 'Reach level 5', icon: '📈' }
-  },
-  completedTutorial: {
-    true: { title: 'Tutorial Master', description: 'Complete the tutorial', icon: '📚' }
+const gameAchievements = AchievementBuilder.combine([
+  // Score achievements with custom awards
+  AchievementBuilder.createScoreAchievement(100)
+    .withAward({ title: 'Century!', description: 'Score 100 points', icon: '🏆' }),
+  AchievementBuilder.createScoreAchievement(500)
+    .withAward({ title: 'High Scorer!', description: 'Score 500 points', icon: '⭐' }),
+
+  // Level achievement
+  AchievementBuilder.createLevelAchievement(5)
+    .withAward({ title: 'Leveling Up', description: 'Reach level 5', icon: '📈' }),
+
+  // Boolean achievement
+  AchievementBuilder.createBooleanAchievement('completedTutorial')
+    .withAward({ title: 'Tutorial Master', description: 'Complete the tutorial', icon: '📚' }),
+
+  // For custom numeric metrics, use Simple API syntax (easiest)
+  {
+    buttonClicks: {
+      10: { title: 'Clicker', description: 'Click 10 times', icon: '👆' },
+      100: { title: 'Super Clicker', description: 'Click 100 times', icon: '🖱️' }
+    }
   },
-  buttonClicks: {
-    10: { title: 'Clicker', description: 'Click 10 times', icon: '👆' },
-    100: { title: 'Super Clicker', description: 'Click 100 times', icon: '🖱️' }
-  }
-};
+
+  // Or use the full builder for complex conditions (Tier 3)
+  AchievementBuilder.create()
+    .withId('speed_demon')
+    .withMetric('buttonClicks')
+    .withCondition((clicks) => typeof clicks === 'number' && clicks >= 50)
+    .withAward({ title: 'Speed Demon', description: 'Click 50 times quickly', icon: '⚡' })
+    .build()
+]);
 
 // Demo component with all essential features  
 const DemoComponent = () => {
@@ -121,10 +153,381 @@ export default App;
 
 When you click "Score 100 points":
 1. A toast notification appears automatically
-2. Confetti animation plays  
+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
 
+## Built-in UI System (NEW in v3.6.0)
+
+React Achievements v3.6.0 introduces a modern, lightweight UI system with **zero external dependencies**. The built-in components provide beautiful notifications, modals, and confetti animations with full theme customization.
+
+### Key Benefits
+
+- **Modern Design**: Sleek gradients, smooth animations, and polished components
+- **Theme System**: 3 built-in themes (modern, minimal, gamified)
+- **Component Injection**: Replace any UI component with your own implementation
+- **Backwards Compatible**: Existing apps work without changes
+- **SSR Safe**: Proper window checks for server-side rendering
+- **Lightweight**: Built-in UI with zero external dependencies
+
+### Quick Migration
+
+**To use built-in UI** - opt-in with the `useBuiltInUI` prop:
+```tsx
+<AchievementProvider
+  achievements={config}
+  useBuiltInUI={true}  // Force built-in UI, ignore external dependencies
+>
+  <YourApp />
+</AchievementProvider>
+```
+
+### Built-in Theme Presets
+
+Choose from 3 professionally designed themes:
+
+#### Modern Theme (Default)
+```tsx
+<AchievementProvider
+  achievements={config}
+  useBuiltInUI={true}
+  ui={{ theme: 'modern' }}
+>
+```
+- Dark gradients with smooth animations
+- Green accent colors
+- Professional and polished look
+- Perfect for productivity apps and games
+
+#### Minimal Theme
+```tsx
+<AchievementProvider
+  achievements={config}
+  useBuiltInUI={true}
+  ui={{ theme: 'minimal' }}
+>
+```
+- Light, clean design
+- Subtle shadows and simple borders
+- Reduced motion for accessibility
+- Perfect for professional and corporate apps
+
+#### Gamified Theme
+```tsx
+<AchievementProvider
+  achievements={config}
+  useBuiltInUI={true}
+  ui={{ theme: 'gamified' }}
+>
+```
+- Perfect for games and engaging experiences
+- Badges instead of rectangular displays
+
+### Notification Positions
+
+Place notifications anywhere on screen:
+
+```tsx
+<AchievementProvider
+  achievements={config}
+  useBuiltInUI={true}
+  ui={{
+    theme: 'modern',
+    notificationPosition: 'top-center',  // Default
+    // Options: 'top-left', 'top-center', 'top-right',
+    //          'bottom-left', 'bottom-center', 'bottom-right'
+  }}
+>
+```
+
+### Custom Component Injection
+
+For advanced users who need full customization beyond the 3 built-in themes, you can replace any UI component with your own implementation:
+
+```tsx
+import { AchievementProvider, NotificationProps } from 'react-achievements';
+
+// Create your custom notification component
+const MyCustomNotification: React.FC<NotificationProps> = ({
+  achievement,
+  onClose,
+  duration,
+}) => {
+  useEffect(() => {
+    const timer = setTimeout(onClose, duration);
+    return () => clearTimeout(timer);
+  }, [duration, onClose]);
+
+  return (
+    <div className="my-custom-notification">
+      <h3>{achievement.title}</h3>
+      <p>{achievement.description}</p>
+      <span>{achievement.icon}</span>
+    </div>
+  );
+};
+
+// Inject your component
+<AchievementProvider
+  achievements={config}
+  ui={{
+    NotificationComponent: MyCustomNotification,
+    // ModalComponent: MyCustomModal,  // Optional
+    // ConfettiComponent: MyCustomConfetti,  // Optional
+  }}
+>
+  <YourApp />
+</AchievementProvider>
+```
+
+### BadgesButton Placement Modes
+
+**NEW**: BadgesButton now supports both fixed positioning and inline mode:
+
+#### Fixed Positioning (Default)
+Traditional floating button:
+```tsx
+import { BadgesButton } from 'react-achievements';
+
+<BadgesButton
+  placement="fixed"  // Default
+  position="bottom-right"  // Corner position
+  onClick={() => setModalOpen(true)}
+  unlockedAchievements={achievements}
+/>
+```
+
+#### Inline Mode (NEW)
+Embed the badge button in drawers, navbars, sidebars:
+```tsx
+function MyDrawer() {
+  const [modalOpen, setModalOpen] = useState(false);
+
+  return (
+    <Drawer>
+      <nav>
+        <NavItem>Home</NavItem>
+        <NavItem>Settings</NavItem>
+
+        {/* Badge button inside drawer - no fixed positioning */}
+        <BadgesButton
+          placement="inline"
+          onClick={() => setModalOpen(true)}
+          unlockedAchievements={achievements}
+          theme="modern"  // Matches your app theme
+        />
+      </nav>
+    </Drawer>
+  );
+}
+```
+
+**Inline mode benefits:**
+- Works in drawers, sidebars, navigation bars
+- Flows with your layout (no fixed positioning)
+- Themeable to match surrounding UI
+- Fully customizable with `styles` prop
+
+### UI Configuration Options
+
+Complete UI configuration reference:
+
+```tsx
+<AchievementProvider
+  achievements={config}
+  useBuiltInUI={true}
+  ui={{
+    // Theme configuration
+    theme: 'modern',  // 'modern' | 'minimal' | 'gamified' | custom theme name
+
+    // Component overrides
+    NotificationComponent: MyCustomNotification,  // Optional
+    ModalComponent: MyCustomModal,  // Optional
+    ConfettiComponent: MyCustomConfetti,  // Optional
+
+    // Notification settings
+    notificationPosition: 'top-center',  // Position on screen
+    enableNotifications: true,  // Default: true
+
+    // Confetti settings
+    enableConfetti: true,  // Default: true
+
+    // Direct theme object (bypasses registry)
+    customTheme: {
+      name: 'inline-theme',
+      notification: { /* ... */ },
+      modal: { /* ... */ },
+      confetti: { /* ... */ },
+    },
+  }}
+>
+  <YourApp />
+</AchievementProvider>
+```
+
+### Migration Guide
+
+#### Existing Users (v3.5.0 and earlier)
+
+**Option 1: No changes (keep using external dependencies)**
+- Your code works exactly as before
+- You'll see a deprecation warning in console (once per session)
+- Plan to migrate before v4.0.0
+
+**Option 2: Migrate to built-in UI**
+1. Add `useBuiltInUI={true}` to your AchievementProvider
+2. Test your app (UI will change to modern theme)
+3. Optionally customize with `ui={{ theme: 'minimal' }}` if you prefer lighter styling
+4. Remove external dependencies:
+   ```bash
+   npm uninstall react-toastify react-modal react-confetti react-use
+   ```
+
+#### New Projects
+
+For new projects using built-in UI, install react-achievements and explicitly opt-in:
+
+```bash
+npm install react-achievements
+```
+
+```tsx
+<AchievementProvider
+  achievements={config}
+  useBuiltInUI={true}  // Explicitly enable built-in UI
+  ui={{ theme: 'modern' }}  // Optional theme customization
+>
+  {/* Beautiful built-in UI */}
+</AchievementProvider>
+```
+
+Without `useBuiltInUI={true}`, you'll need to install the external UI dependencies (default behavior for v3.6.0).
+
+### Built-in UI Component API Reference
+
+The built-in UI system includes three core components that can be used standalone or customized via component injection.
+
+#### BuiltInNotification
+
+Displays achievement unlock notifications.
+
+**Props:**
+- `achievement` (object, required): Achievement object with `id`, `title`, `description`, and `icon`
+- `onClose` (function, optional): Callback to dismiss the notification
+- `duration` (number, optional): Auto-dismiss duration in ms (default: 5000)
+- `position` (string, optional): Notification position - 'top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', or 'bottom-right' (default: 'top-center')
+- `theme` (string | ThemeConfig, optional): Theme name or custom theme config
+
+**Usage:**
+```tsx
+import { BuiltInNotification } from 'react-achievements';
+
+<BuiltInNotification
+  achievement={{
+    id: 'score_100',
+    title: 'Century!',
+    description: 'Score 100 points',
+    icon: '🏆'
+  }}
+  onClose={() => console.log('Dismissed')}
+  duration={5000}
+  position="top-center"
+  theme="modern"
+/>
+```
+
+#### BuiltInModal
+
+Modal dialog for displaying achievement history.
+
+**Props:**
+- `isOpen` (boolean, required): Modal open state
+- `onClose` (function, required): Callback to close modal
+- `achievements` (array, required): Array of achievement objects with `isUnlocked` status
+- `icons` (object, optional): Custom icon mapping
+- `theme` (string | ThemeConfig, optional): Theme name or custom theme config
+
+**Usage:**
+```tsx
+import { BuiltInModal } from 'react-achievements';
+
+<BuiltInModal
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+  achievements={achievementsWithStatus}
+  icons={customIcons}
+  theme="minimal"
+/>
+```
+
+**Note:** This is the internal UI component. For the public API component with `showAllAchievements` support, use `BadgesModal` instead.
+
+#### BuiltInConfetti
+
+Confetti animation component.
+
+**Props:**
+- `show` (boolean, required): Whether confetti is active
+- `duration` (number, optional): Animation duration in ms (default: 5000)
+- `particleCount` (number, optional): Number of confetti particles (default: 50)
+- `colors` (string[], optional): Array of color hex codes (default: ['#FFD700', '#FF6B6B', '#4ECDC4', '#45B7D1', '#96CEB4', '#FFEAA7'])
+
+**Usage:**
+```tsx
+import { BuiltInConfetti } from 'react-achievements';
+
+<BuiltInConfetti
+  show={showConfetti}
+  duration={5000}
+  particleCount={150}
+  colors={['#ff0000', '#00ff00', '#0000ff']}
+/>
+```
+
+**Customization via Component Injection:**
+
+You can replace any built-in component with your own implementation:
+
+```tsx
+import { AchievementProvider, NotificationProps } from 'react-achievements';
+
+const MyCustomNotification: React.FC<NotificationProps> = ({
+  achievement,
+  onClose,
+  duration
+}) => {
+  useEffect(() => {
+    const timer = setTimeout(onClose, duration);
+    return () => clearTimeout(timer);
+  }, [duration, onClose]);
+
+  return (
+    <div className="my-notification">
+      <h3>{achievement.title}</h3>
+      <p>{achievement.description}</p>
+      <span>{achievement.icon}</span>
+    </div>
+  );
+};
+
+<AchievementProvider
+  achievements={config}
+  ui={{
+    NotificationComponent: MyCustomNotification,
+    // ModalComponent: MyCustomModal,
+    // ConfettiComponent: MyCustomConfetti
+  }}
+>
+  <App />
+</AchievementProvider>
+```
+
+### Deprecation Timeline
+
+- **v3.6.0 (current)**: Built-in UI available, external deps optional with deprecation warning
+- **v3.7.0-v3.9.0**: Continued support for both systems, refinements based on feedback
+- **v4.0.0**: External dependencies fully optional, built-in UI becomes default
+
 ## Simple API (Recommended)
 
 Perfect for 90% of use cases - threshold-based achievements with minimal configuration:
@@ -322,6 +725,10 @@ See the [examples directory](./stories/examples) for detailed implementations an
 - Toast notifications
 - Confetti animations
 - TypeScript support
+- **NEW in v3.6.0**: Built-in UI components with zero external dependencies
+- **NEW in v3.6.0**: Extensible theme system with 3 built-in themes (modern, minimal, gamified)
+- **NEW in v3.6.0**: Component injection for full UI customization
+- **NEW in v3.6.0**: BadgesButton inline mode for drawers and sidebars
 - **NEW in v3.4.0**: Async storage support (IndexedDB, REST API, Offline Queue)
 - **NEW in v3.4.0**: 50MB+ storage capacity with IndexedDB
 - **NEW in v3.4.0**: Server-side sync with REST API storage
@@ -367,6 +774,15 @@ To allow users to view their achievement history, the package provides two essen
 
 **Show All Achievements** (NEW in v3.5.0): Display both locked and unlocked achievements to motivate users and show them what's available:
 
+**⚠️ IMPORTANT: Using getAllAchievements with BadgesModal**
+
+When displaying all achievements (locked + unlocked) in the modal, you MUST use the `getAllAchievements()` method from the `useAchievements` hook:
+
+- ✅ **Correct**: `allAchievements={getAllAchievements()}`
+- ❌ **Incorrect**: `allAchievements={achievements.all}`
+
+**Why?** `getAllAchievements()` returns an array of achievement objects with an `isUnlocked: boolean` property that the modal uses to display locked vs unlocked states. The `achievements.all` property is the raw configuration object and doesn't include unlock status information.
+
 ```tsx
 import { useAchievements, BadgesModal } from 'react-achievements';
 
@@ -467,6 +883,25 @@ The library provides a small set of essential fallback icons for system use (err
 
 React Achievements now supports async storage backends for modern applications that need large data capacity, server sync, or offline-first capabilities.
 
+### Choosing the Right Storage
+
+Select the storage option that best fits your application's needs:
+
+| Storage Type | Capacity | Persistence | Network | Offline | Use Case |
+|--------------|----------|-------------|---------|---------|----------|
+| **MemoryStorage** | Unlimited | Session only | No | N/A | Testing, prototypes, temporary state |
+| **LocalStorage** | ~5-10MB | Permanent | No | N/A | Simple apps, browser-only, small datasets |
+| **IndexedDB** | ~50MB+ | Permanent | No | N/A | Large datasets, offline apps, PWAs |
+| **RestAPI** | Unlimited | Server-side | Yes | No | Multi-device sync, cloud backup, user accounts |
+| **OfflineQueue** | Unlimited | Hybrid | Yes | Yes | PWAs, unreliable connections, offline-first apps |
+
+**Decision Tree:**
+- **Need cloud sync or multi-device support?** → Use **RestAPI** or **OfflineQueue**
+- **Large data storage (>10MB)?** → Use **IndexedDB**
+- **Simple browser-only app?** → Use **LocalStorage** (default)
+- **Testing or prototypes only?** → Use **MemoryStorage**
+- **Offline-first with sync?** → Use **OfflineQueue** (wraps RestAPI)
+
 ### IndexedDB Storage
 
 Browser-native storage with 50MB+ capacity (vs localStorage's 5-10MB limit):
@@ -1317,6 +1752,439 @@ The achievement components use default styling that works well out of the box. F
 />
 ```
 
+### Default Styles Reference
+
+The `defaultStyles` export provides access to the default styling configuration for all components. Use this to extend or override specific style properties while keeping other defaults.
+
+```tsx
+import { defaultStyles } from 'react-achievements';
+
+// Access default styles
+console.log(defaultStyles.badgesButton);
+console.log(defaultStyles.badgesModal);
+
+// Extend default styles
+<BadgesButton
+  style={{
+    ...defaultStyles.badgesButton,
+    backgroundColor: '#custom-color',
+    borderRadius: '12px'
+  }}
+  unlockedAchievements={achievements}
+/>
+
+// Override specific properties
+<BadgesModal
+  style={{
+    ...defaultStyles.badgesModal,
+    maxWidth: '800px',
+    padding: '2rem'
+  }}
+  isOpen={isOpen}
+  onClose={onClose}
+  achievements={achievements}
+/>
+```
+
+**Available style objects:**
+- `defaultStyles.badgesButton` - Default button styles
+- `defaultStyles.badgesModal` - Default modal styles
+- `defaultStyles.notification` - Default notification styles (built-in UI)
+- `defaultStyles.confetti` - Default confetti configuration
+
+## Utility Functions & Hooks
+
+### useWindowSize Hook
+
+Returns current window dimensions for responsive UI components.
+
+```tsx
+import { useWindowSize } from 'react-achievements';
+
+const MyComponent = () => {
+  const { width, height } = useWindowSize();
+
+  return (
+    <div>
+      Window size: {width} x {height}
+    </div>
+  );
+};
+```
+
+**Returns:** `{ width: number; height: number }`
+
+**Use cases:**
+- Responsive achievement UI layouts
+- Adaptive modal positioning
+- Mobile vs desktop rendering
+
+### normalizeAchievements Function
+
+Converts Simple API configuration to Complex API format internally. This function is used automatically by the `AchievementProvider`, so you typically don't need to call it directly.
+
+```tsx
+import { normalizeAchievements } from 'react-achievements';
+
+const simpleConfig = {
+  score: {
+    100: { title: 'Century!', icon: '🏆' }
+  }
+};
+
+const normalized = normalizeAchievements(simpleConfig);
+// Returns complex format used internally
+```
+
+**Note:** Usually not needed - the provider handles this automatically.
+
+### isSimpleConfig Type Guard
+
+Check if a configuration object uses the Simple API format.
+
+```tsx
+import { isSimpleConfig } from 'react-achievements';
+
+if (isSimpleConfig(myConfig)) {
+  console.log('Using Simple API format');
+} else {
+  console.log('Using Complex API format');
+}
+```
+
+**Returns:** `boolean`
+
+## TypeScript Type Reference
+
+### Core Types
+
+#### AchievementWithStatus
+
+Achievement object with unlock status (returned by `getAllAchievements()`).
+
+```tsx
+interface AchievementWithStatus {
+  achievementId: string;
+  achievementTitle: string;
+  achievementDescription?: string;
+  achievementIconKey?: string;
+  isUnlocked: boolean;
+}
+```
+
+#### AchievementMetrics
+
+Metrics tracked for achievements.
+
+```tsx
+type AchievementMetrics = Record<string, AchievementMetricValue>;
+type AchievementMetricValue = number | string | boolean | Date | null | undefined;
+```
+
+**Example:**
+```tsx
+const metrics: AchievementMetrics = {
+  score: 100,
+  level: 5,
+  completedTutorial: true,
+  lastLoginDate: new Date()
+};
+```
+
+#### UIConfig
+
+UI configuration for built-in components.
+
+```tsx
+interface UIConfig {
+  theme?: 'modern' | 'minimal' | 'gamified' | string;
+  customTheme?: ThemeConfig;
+  NotificationComponent?: React.ComponentType<NotificationProps>;
+  ModalComponent?: React.ComponentType<ModalProps>;
+  ConfettiComponent?: React.ComponentType<ConfettiProps>;
+  notificationPosition?: NotificationPosition;
+  enableNotifications?: boolean;
+  enableConfetti?: boolean;
+}
+```
+
+#### StorageType Enum
+
+```tsx
+enum StorageType {
+  Local = 'local',
+  Memory = 'memory',
+  IndexedDB = 'indexeddb',
+  RestAPI = 'restapi'
+}
+```
+
+**Usage:**
+```tsx
+<AchievementProvider storage={StorageType.IndexedDB}>
+```
+
+### Storage Interfaces
+
+#### AchievementStorage (Synchronous)
+
+```tsx
+interface AchievementStorage {
+  getMetrics(): AchievementMetrics;
+  setMetrics(metrics: AchievementMetrics): void;
+  getUnlockedAchievements(): string[];
+  setUnlockedAchievements(achievements: string[]): void;
+  clear(): void;
+}
+```
+
+#### AsyncAchievementStorage
+
+```tsx
+interface AsyncAchievementStorage {
+  getMetrics(): Promise<AchievementMetrics>;
+  setMetrics(metrics: AchievementMetrics): Promise<void>;
+  getUnlockedAchievements(): Promise<string[]>;
+  setUnlockedAchievements(achievements: string[]): Promise<void>;
+  clear(): Promise<void>;
+}
+```
+
+#### RestApiStorageConfig
+
+```tsx
+interface RestApiStorageConfig {
+  baseUrl: string;
+  userId: string;
+  headers?: Record<string, string>;
+  timeout?: number; // milliseconds, default: 10000
+}
+```
+
+**Example:**
+```tsx
+const config: RestApiStorageConfig = {
+  baseUrl: 'https://api.example.com',
+  userId: 'user123',
+  headers: {
+    'Authorization': 'Bearer token'
+  },
+  timeout: 15000
+};
+```
+
+### Import/Export Types
+
+#### ImportOptions
+
+```tsx
+interface ImportOptions {
+  strategy?: 'replace' | 'merge' | 'preserve';
+  validate?: boolean;
+  expectedConfigHash?: string;
+}
+```
+
+**Strategies:**
+- `replace`: Completely replace all existing data
+- `merge`: Combine imported and existing data (takes maximum values)
+- `preserve`: Only import new achievements, keep existing data
+
+#### ImportResult
+
+```tsx
+interface ImportResult {
+  success: boolean;
+  errors?: string[];
+  warnings?: string[];
+  imported?: {
+    metrics: number;
+    achievements: number;
+  };
+  mergedMetrics?: AchievementMetrics;
+  mergedUnlocked?: string[];
+  configMismatch?: boolean;
+}
+```
+
+## Common Patterns & Recipes
+
+Quick reference for common use cases and patterns.
+
+### Pattern 1: Display Only Unlocked Achievements
+
+Show users only the achievements they've unlocked:
+
+```tsx
+import { useAchievements, BadgesModal } from 'react-achievements';
+
+function MyComponent() {
+  const { achievements } = useAchievements();
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <BadgesModal
+      isOpen={isOpen}
+      onClose={() => setIsOpen(false)}
+      achievements={achievements.unlocked}  // Only unlocked IDs
+    />
+  );
+}
+```
+
+### Pattern 2: Display All Achievements (Locked + Unlocked)
+
+Show both locked and unlocked achievements to motivate users:
+
+```tsx
+import { useAchievements, BadgesModal } from 'react-achievements';
+
+function MyComponent() {
+  const { getAllAchievements } = useAchievements();
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <BadgesModal
+      isOpen={isOpen}
+      onClose={() => setIsOpen(false)}
+      showAllAchievements={true}
+      allAchievements={getAllAchievements()}  // ⭐ Required!
+      showUnlockConditions={true}  // Show hints
+    />
+  );
+}
+```
+
+### Pattern 3: Export Achievement Data
+
+Allow users to download their achievement progress:
+
+```tsx
+import { useAchievements } from 'react-achievements';
+
+function MyComponent() {
+  const { exportData } = useAchievements();
+
+  const handleExport = () => {
+    const jsonString = exportData();
+
+    // Create downloadable file
+    const blob = new Blob([jsonString], { type: 'application/json' });
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = `achievements-${Date.now()}.json`;
+    link.click();
+    URL.revokeObjectURL(url);
+  };
+
+  return <button onClick={handleExport}>Export Progress</button>;
+}
+```
+
+### Pattern 4: Import Achievement Data
+
+Restore achievements from a backup:
+
+```tsx
+import { useAchievements } from 'react-achievements';
+
+function MyComponent() {
+  const { importData, update } = useAchievements();
+
+  const handleImport = async (file: File) => {
+    const text = await file.text();
+    const result = importData(text, {
+      strategy: 'merge',  // Combine with existing data
+      validate: true
+    });
+
+    if (result.success && result.mergedMetrics) {
+      update(result.mergedMetrics);
+      alert(`Imported ${result.imported?.achievements} achievements!`);
+    } else {
+      alert('Import failed: ' + result.errors?.join(', '));
+    }
+  };
+
+  return (
+    <input
+      type="file"
+      accept=".json"
+      onChange={(e) => e.target.files?.[0] && handleImport(e.target.files[0])}
+    />
+  );
+}
+```
+
+### Pattern 5: Get Current Metrics
+
+Check achievement progress programmatically:
+
+```tsx
+import { useAchievements } from 'react-achievements';
+
+function MyComponent() {
+  const { getState } = useAchievements();
+
+  const handleCheckProgress = () => {
+    const state = getState();
+    console.log('Current metrics:', state.metrics);
+    console.log('Unlocked achievements:', state.unlocked);
+    console.log('Total unlocked:', state.unlocked.length);
+  };
+
+  return <button onClick={handleCheckProgress}>Check Progress</button>;
+}
+```
+
+### Pattern 6: Track Complex Events
+
+Handle achievements based on multiple conditions:
+
+```tsx
+import { useSimpleAchievements } from 'react-achievements';
+
+function GameComponent() {
+  const { track, trackMultiple } = useSimpleAchievements();
+
+  const handleLevelComplete = (score: number, time: number, accuracy: number) => {
+    // Track multiple related metrics at once
+    trackMultiple({
+      score: score,
+      completionTime: time,
+      accuracy: accuracy,
+      levelsCompleted: true
+    });
+
+    // Achievements with custom conditions will evaluate all metrics
+    // Example: "Perfect Level" achievement for score > 1000 AND accuracy === 100
+  };
+
+  return <button onClick={() => handleLevelComplete(1200, 45, 100)}>Complete Level</button>;
+}
+```
+
+### Pattern 7: Reset Progress
+
+Clear all achievement data:
+
+```tsx
+import { useAchievements } from 'react-achievements';
+
+function SettingsComponent() {
+  const { reset } = useAchievements();
+
+  const handleReset = () => {
+    if (confirm('Are you sure? This will delete all achievement progress.')) {
+      reset();
+      alert('All achievements have been reset!');
+    }
+  };
+
+  return <button onClick={handleReset}>Reset All Achievements</button>;
+}
+```
 
 ## API Reference
 
@@ -1332,11 +2200,243 @@ The achievement components use default styling that works well out of the box. F
 
 ### useAchievements Hook
 
-Returns an object with:
+The `useAchievements` hook provides access to all achievement functionality. It must be used within an `AchievementProvider`.
+
+```tsx
+const {
+  update,
+  achievements,
+  reset,
+  getState,
+  exportData,
+  importData,
+  getAllAchievements
+} = useAchievements();
+```
+
+#### Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `update` | `(metrics: Record<string, any>) => void` | Update one or more achievement metrics. Triggers achievement evaluation. |
+| `achievements` | `{ unlocked: string[]; all: Record<string, any> }` | Object containing arrays of unlocked achievement IDs and the full configuration. |
+| `reset` | `() => void` | Clear all achievement data including metrics and unlock history. |
+| `getState` | `() => { metrics: AchievementMetrics; unlocked: string[] }` | Get current state with metrics (in array format) and unlocked IDs. |
+| `exportData` | `() => string` | Export all achievement data as JSON string for backup/transfer. |
+| `importData` | `(jsonString: string, options?: ImportOptions) => ImportResult` | Import previously exported data with merge strategies. |
+| `getAllAchievements` | `() => AchievementWithStatus[]` | **Get all achievements with unlock status. Required for `BadgesModal` when showing locked achievements.** |
+
+#### Method Details
+
+**`update(metrics: Record<string, any>): void`**
+
+Update achievement metrics and trigger evaluation of achievement conditions.
+
+```tsx
+// Single metric
+update({ score: 100 });
+
+// Multiple metrics
+update({ score: 500, level: 10 });
+```
+
+**`achievements: { unlocked: string[]; all: Record<string, any> }`**
+
+Object containing current achievement state.
+
+```tsx
+// Get unlocked achievement IDs
+console.log(achievements.unlocked); // ['score_100', 'level_5']
+
+// Get count of unlocked achievements
+const count = achievements.unlocked.length;
+```
+
+**`reset(): void`**
+
+Clear all achievement data including metrics, unlocked achievements, and notification history.
+
+```tsx
+// Reset all achievements
+reset();
+```
+
+**`getState(): { metrics: AchievementMetrics; unlocked: string[] }`**
+
+Get the current achievement state including metrics and unlocked achievement IDs.
+
+```tsx
+const state = getState();
+console.log('Current metrics:', state.metrics);
+console.log('Unlocked achievements:', state.unlocked);
+```
+
+**Note:** Metrics are returned in array format (e.g., `{ score: [100] }`) even if you passed scalar values.
+
+**`exportData(): string`**
+
+Export all achievement data as a JSON string for backup or transfer.
 
-- `update`: Function to update achievement metrics
-- `achievements`: Object containing unlocked and locked achievements
-- `reset`: Function to reset achievement storage
+```tsx
+const jsonString = exportData();
+
+// Save to file
+const blob = new Blob([jsonString], { type: 'application/json' });
+const url = URL.createObjectURL(blob);
+const link = document.createElement('a');
+link.href = url;
+link.download = `achievements-${Date.now()}.json`;
+link.click();
+```
+
+**`importData(jsonString: string, options?: ImportOptions): ImportResult`**
+
+Import previously exported achievement data.
+
+```tsx
+const result = importData(jsonString, {
+  strategy: 'merge', // 'replace', 'merge', or 'preserve'
+  validate: true
+});
+
+if (result.success) {
+  console.log(`Imported ${result.imported.achievements} achievements`);
+}
+```
+
+**`getAllAchievements(): AchievementWithStatus[]`**
+
+Returns all achievements (locked and unlocked) with their status. **This is required when using `BadgesModal` with `showAllAchievements={true}`**.
+
+```tsx
+const allAchievements = getAllAchievements();
+// Returns: [
+//   { achievementId: 'score_100', achievementTitle: 'Century!', isUnlocked: true, ... },
+//   { achievementId: 'score_500', achievementTitle: 'High Scorer!', isUnlocked: false, ... }
+// ]
+
+// Use with BadgesModal to show all achievements
+<BadgesModal
+  showAllAchievements={true}
+  allAchievements={allAchievements}
+  // ... other props
+/>
+```
+
+**Note:** Use `achievements.unlocked` for simple cases where you only need IDs. Use `getAllAchievements()` when you need full achievement objects with unlock status.
+
+### useSimpleAchievements Hook
+
+Simplified wrapper around `useAchievements` with cleaner API for common use cases.
+
+```tsx
+const {
+  track,
+  increment,
+  trackMultiple,
+  unlocked,
+  all,
+  unlockedCount,
+  reset,
+  getState,
+  exportData,
+  importData,
+  getAllAchievements
+} = useSimpleAchievements();
+```
+
+#### Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `track` | `(metric: string, value: any) => void` | Update a single metric value. |
+| `increment` | `(metric: string, amount?: number) => void` | Increment a metric by amount (default: 1). |
+| `trackMultiple` | `(metrics: Record<string, any>) => void` | Update multiple metrics at once. |
+| `unlocked` | `string[]` | Array of unlocked achievement IDs. |
+| `all` | `Record<string, any>` | All achievements configuration. |
+| `unlockedCount` | `number` | Number of unlocked achievements. |
+| `reset` | `() => void` | Clear all achievement data. |
+| `getState` | `() => { metrics; unlocked }` | Get current state. |
+| `exportData` | `() => string` | Export data as JSON. |
+| `importData` | `(json, options) => ImportResult` | Import data. |
+| `getAllAchievements` | `() => AchievementWithStatus[]` | Get all achievements with status. |
+
+**Example:**
+
+```tsx
+const { track, increment, unlocked, unlockedCount } = useSimpleAchievements();
+
+// Track single metrics
+track('score', 100);
+track('completedTutorial', true);
+
+// Increment values (great for clicks, actions, etc.)
+increment('buttonClicks');     // Adds 1
+increment('score', 50);        // Adds 50
+
+// Check progress
+console.log(`Unlocked ${unlockedCount} achievements`);
+console.log('Achievement IDs:', unlocked);
+```
+
+### Component Props Reference
+
+#### BadgesButton Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `onClick` | `() => void` | Yes | Handler for button click |
+| `unlockedAchievements` | `AchievementDetails[]` | Yes | Array of unlocked achievements |
+| `position` | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | No | Fixed position (default: 'bottom-right') |
+| `placement` | `'fixed' \| 'inline'` | No | Positioning mode (default: 'fixed') |
+| `theme` | `string \| ThemeConfig` | No | Theme name or custom theme |
+| `style` | `React.CSSProperties` | No | Custom styles |
+| `icons` | `Record<string, string>` | No | Custom icon mapping |
+
+**Example:**
+```tsx
+<BadgesButton
+  onClick={() => setModalOpen(true)}
+  unlockedAchievements={achievements.unlocked}
+  position="bottom-right"
+  placement="fixed"
+  theme="modern"
+/>
+```
+
+#### BadgesModal Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `isOpen` | `boolean` | Yes | Modal open state |
+| `onClose` | `() => void` | Yes | Close handler |
+| `achievements` | `AchievementDetails[]` | Yes* | Unlocked achievements (*not used if `showAllAchievements`) |
+| `showAllAchievements` | `boolean` | No | Show locked + unlocked (default: false) |
+| `showUnlockConditions` | `boolean` | No | Show unlock hints (default: false) |
+| `allAchievements` | `AchievementWithStatus[]` | No* | All achievements with status (*required if `showAllAchievements`) |
+| `icons` | `Record<string, string>` | No | Custom icon mapping |
+| `style` | `React.CSSProperties` | No | Custom styles |
+
+**Example (unlocked only):**
+```tsx
+<BadgesModal
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+  achievements={achievements.unlocked}
+/>
+```
+
+**Example (all achievements):**
+```tsx
+const { getAllAchievements } = useAchievements();
+
+<BadgesModal
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+  showAllAchievements={true}
+  allAchievements={getAllAchievements()}  // Required!
+/>
+```
 
 ## Advanced: Complex API