react-achievements 3.7.0 → 3.8.0

package/dist/index.esm.js

@@ -0,0 +1,1354 @@
+import { AchievementEngine } from 'achievements-engine';
+export { AchievementBuilder, AchievementEngine, AchievementError, AsyncStorageAdapter, ConfigurationError, ImportValidationError, IndexedDBStorage, LocalStorage, MemoryStorage, OfflineQueueStorage, RestApiStorage, StorageError, StorageQuotaError, StorageType, SyncError, createConfigHash, exportAchievementData, importAchievementData, isAchievementError, isRecoverableError, isSimpleConfig, normalizeAchievements } from 'achievements-engine';
+import React, { useState, useEffect, createContext, useRef, useContext } from 'react';
+import Modal from 'react-modal';
+import Confetti from 'react-confetti';
+
+// Type guard to detect async storage
+function isAsyncStorage(storage) {
+    // Check if methods return Promises
+    const testResult = storage.getMetrics();
+    return testResult && typeof testResult.then === 'function';
+}
+var StorageType;
+(function (StorageType) {
+    StorageType["Local"] = "local";
+    StorageType["Memory"] = "memory";
+    StorageType["IndexedDB"] = "indexeddb";
+    StorageType["RestAPI"] = "restapi"; // Asynchronous REST API storage
+})(StorageType || (StorageType = {}));
+
+/**
+ * Built-in theme presets
+ */
+const builtInThemes = {
+    /**
+     * Modern theme - Dark gradients with vibrant accents
+     * Inspired by contemporary achievement systems (Discord, Steam, Xbox)
+     */
+    modern: {
+        name: 'modern',
+        notification: {
+            background: 'linear-gradient(135deg, rgba(30, 30, 50, 0.98) 0%, rgba(50, 50, 70, 0.98) 100%)',
+            textColor: '#ffffff',
+            accentColor: '#4CAF50',
+            borderRadius: '12px',
+            boxShadow: '0 8px 32px rgba(0, 0, 0, 0.4)',
+            fontSize: {
+                header: '12px',
+                title: '18px',
+                description: '14px',
+            },
+        },
+        modal: {
+            overlayColor: 'rgba(0, 0, 0, 0.85)',
+            background: 'linear-gradient(135deg, #1e1e32 0%, #323246 100%)',
+            textColor: '#ffffff',
+            accentColor: '#4CAF50',
+            borderRadius: '16px',
+            headerFontSize: '28px',
+        },
+        confetti: {
+            colors: ['#FFD700', '#4CAF50', '#2196F3', '#FF6B6B'],
+            particleCount: 50,
+            shapes: ['circle', 'square'],
+        },
+    },
+    /**
+     * Minimal theme - Clean, light design with subtle accents
+     * Perfect for professional or minimalist applications
+     */
+    minimal: {
+        name: 'minimal',
+        notification: {
+            background: 'rgba(255, 255, 255, 0.98)',
+            textColor: '#333333',
+            accentColor: '#4CAF50',
+            borderRadius: '8px',
+            boxShadow: '0 4px 12px rgba(0, 0, 0, 0.15)',
+            fontSize: {
+                header: '11px',
+                title: '16px',
+                description: '13px',
+            },
+        },
+        modal: {
+            overlayColor: 'rgba(0, 0, 0, 0.5)',
+            background: '#ffffff',
+            textColor: '#333333',
+            accentColor: '#4CAF50',
+            borderRadius: '12px',
+            headerFontSize: '24px',
+        },
+        confetti: {
+            colors: ['#4CAF50', '#2196F3'],
+            particleCount: 30,
+            shapes: ['circle'],
+        },
+    },
+    /**
+     * Gamified theme - Modern gaming aesthetic with sci-fi colors
+     * Dark navy backgrounds with cyan and orange accents (2024 gaming trend)
+     * Features square/badge-shaped achievement cards
+     */
+    gamified: {
+        name: 'gamified',
+        notification: {
+            background: 'linear-gradient(135deg, rgba(5, 8, 22, 0.98) 0%, rgba(15, 23, 42, 0.98) 100%)',
+            textColor: '#22d3ee', // Bright cyan
+            accentColor: '#f97316', // Bright orange
+            borderRadius: '6px',
+            boxShadow: '0 8px 32px rgba(34, 211, 238, 0.4), 0 0 20px rgba(249, 115, 22, 0.3)',
+            fontSize: {
+                header: '13px',
+                title: '20px',
+                description: '15px',
+            },
+        },
+        modal: {
+            overlayColor: 'rgba(5, 8, 22, 0.85)',
+            background: 'linear-gradient(135deg, #0f172a 0%, #050816 100%)',
+            textColor: '#22d3ee', // Bright cyan
+            accentColor: '#f97316', // Bright orange
+            borderRadius: '8px',
+            headerFontSize: '32px',
+            achievementCardBorderRadius: '8px', // Square badge-like cards
+            achievementLayout: 'badge', // Use badge/grid layout instead of horizontal list
+        },
+        confetti: {
+            colors: ['#22d3ee', '#f97316', '#a855f7', '#eab308'], // Cyan, orange, purple, yellow
+            particleCount: 100,
+            shapes: ['circle', 'square'],
+        },
+    },
+};
+/**
+ * Retrieve a theme by name (internal use only)
+ * Only checks built-in themes
+ *
+ * @param name - Theme name (built-in only)
+ * @returns Theme configuration or undefined if not found
+ * @internal
+ */
+function getTheme(name) {
+    return builtInThemes[name];
+}
+
+const getPositionStyles = (position) => {
+    const base = {
+        position: 'fixed',
+        margin: '20px',
+        zIndex: 1000,
+    };
+    switch (position) {
+        case 'top-left':
+            return Object.assign(Object.assign({}, base), { top: 0, left: 0 });
+        case 'top-right':
+            return Object.assign(Object.assign({}, base), { top: 0, right: 0 });
+        case 'bottom-left':
+            return Object.assign(Object.assign({}, base), { bottom: 0, left: 0 });
+        case 'bottom-right':
+            return Object.assign(Object.assign({}, base), { bottom: 0, right: 0 });
+    }
+};
+const BadgesButton = ({ onClick, position = 'bottom-right', placement = 'fixed', styles = {}, unlockedAchievements, theme = 'modern', }) => {
+    // Get theme configuration for consistent styling
+    const themeConfig = getTheme(theme) || builtInThemes.modern;
+    const accentColor = themeConfig.notification.accentColor;
+    // Different styling for fixed vs inline placement
+    const baseStyles = placement === 'inline'
+        ? Object.assign({ 
+            // Inline mode: looks like a navigation item
+            backgroundColor: 'transparent', color: themeConfig.notification.textColor, padding: '12px 16px', border: 'none', borderRadius: '6px', cursor: 'pointer', display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: '8px', fontSize: '15px', width: '100%', textAlign: 'left', transition: 'background-color 0.2s ease-in-out' }, styles) : Object.assign(Object.assign({ 
+        // Fixed mode: floating button
+        backgroundColor: accentColor, color: 'white', padding: '10px 20px', border: 'none', borderRadius: '20px', cursor: 'pointer', display: 'flex', alignItems: 'center', gap: '8px', fontSize: '16px', boxShadow: '0 2px 5px rgba(0,0,0,0.2)', transition: 'transform 0.2s ease-in-out' }, getPositionStyles(position)), styles);
+    return (React.createElement("button", { onClick: onClick, style: baseStyles, onMouseEnter: (e) => {
+            if (placement === 'inline') {
+                // Inline mode: subtle background color change
+                e.target.style.backgroundColor = 'rgba(255, 255, 255, 0.1)';
+            }
+            else {
+                // Fixed mode: scale transformation
+                e.target.style.transform = 'scale(1.05)';
+            }
+        }, onMouseLeave: (e) => {
+            if (placement === 'inline') {
+                e.target.style.backgroundColor = 'transparent';
+            }
+            else {
+                e.target.style.transform = 'scale(1)';
+            }
+        }, "data-placement": placement, "data-testid": "badges-button" },
+        "\uD83C\uDFC6 Achievements (",
+        unlockedAchievements.length,
+        ")"));
+};
+
+const defaultAchievementIcons = {
+    // Essential fallback icons for system use
+    default: '⭐', // Fallback when no icon is provided
+    loading: '⏳', // For loading states
+    error: '⚠️', // For error states
+    success: '✅', // For success states
+    // A few common icons for backward compatibility
+    trophy: '🏆',
+    star: '⭐',
+};
+
+const defaultStyles = {
+    badgesButton: {
+        backgroundColor: '#4CAF50',
+        color: 'white',
+        padding: '10px 20px',
+        border: 'none',
+        borderRadius: '20px',
+        cursor: 'pointer',
+        display: 'flex',
+        alignItems: 'center',
+        gap: '8px',
+        fontSize: '16px',
+        boxShadow: '0 2px 5px rgba(0,0,0,0.2)',
+        transition: 'transform 0.2s ease-in-out',
+    },
+    badgesModal: {
+        overlay: {
+            backgroundColor: 'rgba(0, 0, 0, 0.75)',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            zIndex: 1000,
+        },
+        content: {
+            position: 'relative',
+            background: '#fff',
+            borderRadius: '8px',
+            padding: '20px',
+            maxWidth: '500px',
+            width: '90%',
+            maxHeight: '80vh',
+            overflow: 'auto',
+        },
+        header: {
+            display: 'flex',
+            justifyContent: 'space-between',
+            alignItems: 'center',
+            marginBottom: '20px',
+        },
+        closeButton: {
+            background: 'none',
+            border: 'none',
+            fontSize: '24px',
+            cursor: 'pointer',
+            padding: '0',
+        },
+        achievementList: {
+            display: 'flex',
+            flexDirection: 'column',
+            gap: '16px',
+        },
+        achievementItem: {
+            display: 'flex',
+            gap: '16px',
+            padding: '16px',
+            borderRadius: '8px',
+            backgroundColor: '#f5f5f5',
+            alignItems: 'center',
+        },
+        achievementTitle: {
+            margin: '0',
+            fontSize: '18px',
+            fontWeight: 'bold',
+        },
+        achievementDescription: {
+            margin: '4px 0 0 0',
+            color: '#666',
+        },
+        achievementIcon: {
+            fontSize: '32px',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+        },
+        lockIcon: {
+            fontSize: '24px',
+            position: 'absolute',
+            top: '50%',
+            right: '16px',
+            transform: 'translateY(-50%)',
+        },
+        lockedAchievementItem: {
+            display: 'flex',
+            gap: '16px',
+            padding: '16px',
+            borderRadius: '8px',
+            backgroundColor: '#e0e0e0',
+            alignItems: 'center',
+            opacity: 0.5,
+        },
+    },
+};
+
+const BadgesModal = ({ isOpen, onClose, achievements, styles = {}, icons = {}, showAllAchievements = false, showUnlockConditions = false, allAchievements, }) => {
+    // Merge custom icons with default icons, with custom icons taking precedence
+    const mergedIcons = Object.assign(Object.assign({}, defaultAchievementIcons), icons);
+    return (React.createElement(Modal, { isOpen: isOpen, onRequestClose: onClose, style: {
+            overlay: Object.assign(Object.assign({}, defaultStyles.badgesModal.overlay), styles === null || styles === void 0 ? void 0 : styles.overlay),
+            content: Object.assign(Object.assign({}, defaultStyles.badgesModal.content), styles === null || styles === void 0 ? void 0 : styles.content)
+        }, contentLabel: "Achievements" },
+        React.createElement("div", { style: Object.assign(Object.assign({}, defaultStyles.badgesModal.header), styles === null || styles === void 0 ? void 0 : styles.header) },
+            React.createElement("h2", { style: { margin: 0 } }, "\uD83C\uDFC6 Achievements"),
+            React.createElement("button", { onClick: onClose, style: Object.assign(Object.assign({}, defaultStyles.badgesModal.closeButton), styles === null || styles === void 0 ? void 0 : styles.closeButton), "aria-label": "Close" }, "\u00D7")),
+        React.createElement("div", { style: Object.assign(Object.assign({}, defaultStyles.badgesModal.achievementList), styles === null || styles === void 0 ? void 0 : styles.achievementList) }, (() => {
+            // Determine which achievements to display
+            const achievementsToDisplay = showAllAchievements && allAchievements
+                ? allAchievements
+                : achievements.map(a => (Object.assign(Object.assign({}, a), { isUnlocked: true })));
+            return (React.createElement(React.Fragment, null,
+                achievementsToDisplay.map((achievement) => {
+                    const isLocked = !achievement.isUnlocked;
+                    return (React.createElement("div", { key: achievement.achievementId, style: Object.assign(Object.assign(Object.assign({}, (isLocked
+                            ? Object.assign(Object.assign({}, defaultStyles.badgesModal.lockedAchievementItem), styles === null || styles === void 0 ? void 0 : styles.lockedAchievementItem) : defaultStyles.badgesModal.achievementItem)), styles === null || styles === void 0 ? void 0 : styles.achievementItem), { position: 'relative' }) },
+                        achievement.achievementIconKey && (React.createElement("div", { style: Object.assign(Object.assign(Object.assign({}, defaultStyles.badgesModal.achievementIcon), styles === null || styles === void 0 ? void 0 : styles.achievementIcon), { opacity: isLocked ? 0.4 : 1 }) }, achievement.achievementIconKey in mergedIcons
+                            ? mergedIcons[achievement.achievementIconKey]
+                            : mergedIcons.default || '⭐')),
+                        React.createElement("div", { style: { flex: 1 } },
+                            React.createElement("h3", { style: Object.assign(Object.assign(Object.assign({}, defaultStyles.badgesModal.achievementTitle), styles === null || styles === void 0 ? void 0 : styles.achievementTitle), { color: isLocked ? '#999' : undefined }) }, achievement.achievementTitle),
+                            React.createElement("p", { style: Object.assign(Object.assign(Object.assign({}, defaultStyles.badgesModal.achievementDescription), styles === null || styles === void 0 ? void 0 : styles.achievementDescription), { color: isLocked ? '#aaa' : '#666' }) },
+                                achievement.achievementDescription,
+                                showUnlockConditions && isLocked && achievement.achievementDescription && (React.createElement("span", { style: {
+                                        display: 'block',
+                                        fontSize: '12px',
+                                        marginTop: '4px',
+                                        fontStyle: 'italic',
+                                        color: '#888'
+                                    } },
+                                    "\uD83D\uDD13 ",
+                                    achievement.achievementDescription)))),
+                        isLocked && (React.createElement("div", { style: Object.assign(Object.assign({}, defaultStyles.badgesModal.lockIcon), styles === null || styles === void 0 ? void 0 : styles.lockIcon) }, "\uD83D\uDD12"))));
+                }),
+                achievementsToDisplay.length === 0 && (React.createElement("p", { style: { textAlign: 'center', color: '#666' } }, "No achievements configured."))));
+        })())));
+};
+
+/**
+ * BadgesButtonWithModal - A convenience component that combines BadgesButton and BadgesModal
+ *
+ * This component manages the modal state internally, providing a simplified API
+ * for the common use case of displaying achievements.
+ *
+ * For advanced use cases requiring custom state management or multiple triggers,
+ * use BadgesButton and BadgesModal separately.
+ *
+ * @example
+ * ```tsx
+ * // Simple usage
+ * <BadgesButtonWithModal
+ *   unlockedAchievements={achievements.unlocked}
+ * />
+ *
+ * // Show all achievements (locked + unlocked)
+ * <BadgesButtonWithModal
+ *   unlockedAchievements={achievements.unlocked}
+ *   showAllAchievements={true}
+ *   allAchievements={getAllAchievements()}
+ *   showUnlockConditions={true}
+ * />
+ *
+ * // Customize position and theme
+ * <BadgesButtonWithModal
+ *   unlockedAchievements={achievements.unlocked}
+ *   position="top-right"
+ *   theme="gamified"
+ * />
+ *
+ * // Inline mode for navigation
+ * <BadgesButtonWithModal
+ *   unlockedAchievements={achievements.unlocked}
+ *   placement="inline"
+ * />
+ * ```
+ */
+const BadgesButtonWithModal = ({ unlockedAchievements, position = 'bottom-right', placement = 'fixed', showAllAchievements = false, allAchievements, showUnlockConditions = false, icons, theme = 'modern', buttonStyles, modalStyles, }) => {
+    const [isModalOpen, setIsModalOpen] = useState(false);
+    return (React.createElement(React.Fragment, null,
+        React.createElement(BadgesButton, { onClick: () => setIsModalOpen(true), unlockedAchievements: unlockedAchievements, position: position, placement: placement, theme: theme, styles: buttonStyles }),
+        React.createElement(BadgesModal, { isOpen: isModalOpen, onClose: () => setIsModalOpen(false), achievements: unlockedAchievements, showAllAchievements: showAllAchievements, allAchievements: allAchievements, showUnlockConditions: showUnlockConditions, icons: icons, styles: modalStyles })));
+};
+
+/**
+ * Hook to track window dimensions
+ * Replacement for react-use's useWindowSize
+ *
+ * @returns Object with width and height properties
+ *
+ * @example
+ * ```tsx
+ * const { width, height } = useWindowSize();
+ * console.log(`Window size: ${width}x${height}`);
+ * ```
+ */
+function useWindowSize() {
+    const [size, setSize] = useState({
+        width: typeof window !== 'undefined' ? window.innerWidth : 0,
+        height: typeof window !== 'undefined' ? window.innerHeight : 0,
+    });
+    useEffect(() => {
+        // Handle SSR - window may not be defined
+        if (typeof window === 'undefined') {
+            return;
+        }
+        const handleResize = () => {
+            setSize({
+                width: window.innerWidth,
+                height: window.innerHeight,
+            });
+        };
+        // Set initial size
+        handleResize();
+        // Add event listener
+        window.addEventListener('resize', handleResize);
+        // Cleanup
+        return () => {
+            window.removeEventListener('resize', handleResize);
+        };
+    }, []);
+    return size;
+}
+
+const ConfettiWrapper = ({ show }) => {
+    const { width, height } = useWindowSize();
+    if (!show)
+        return null;
+    return (React.createElement(Confetti, { width: width, height: height, numberOfPieces: 200, recycle: false, style: {
+            position: 'fixed',
+            top: 0,
+            left: 0,
+            zIndex: 1001,
+            pointerEvents: 'none',
+        } }));
+};
+
+/**
+ * Built-in notification component
+ * Modern, theme-aware achievement notification with smooth animations
+ */
+const BuiltInNotification = ({ achievement, onClose, duration = 5000, position = 'top-center', theme = 'modern', icons = {}, }) => {
+    var _a, _b, _c;
+    const [isVisible, setIsVisible] = useState(false);
+    const [isExiting, setIsExiting] = useState(false);
+    // Merge custom icons with defaults
+    const mergedIcons = Object.assign(Object.assign({}, defaultAchievementIcons), icons);
+    // Get theme configuration
+    const themeConfig = getTheme(theme) || builtInThemes.modern;
+    const { notification: themeStyles } = themeConfig;
+    useEffect(() => {
+        // Slide in animation
+        const showTimer = setTimeout(() => setIsVisible(true), 10);
+        // Auto-dismiss
+        const dismissTimer = setTimeout(() => {
+            setIsExiting(true);
+            setTimeout(() => onClose === null || onClose === void 0 ? void 0 : onClose(), 300);
+        }, duration);
+        return () => {
+            clearTimeout(showTimer);
+            clearTimeout(dismissTimer);
+        };
+    }, [duration, onClose]);
+    const getPositionStyles = () => {
+        const base = {
+            position: 'fixed',
+            zIndex: 9999,
+        };
+        switch (position) {
+            case 'top-center':
+                return Object.assign(Object.assign({}, base), { top: 20, left: '50%', transform: 'translateX(-50%)' });
+            case 'top-left':
+                return Object.assign(Object.assign({}, base), { top: 20, left: 20 });
+            case 'top-right':
+                return Object.assign(Object.assign({}, base), { top: 20, right: 20 });
+            case 'bottom-center':
+                return Object.assign(Object.assign({}, base), { bottom: 20, left: '50%', transform: 'translateX(-50%)' });
+            case 'bottom-left':
+                return Object.assign(Object.assign({}, base), { bottom: 20, left: 20 });
+            case 'bottom-right':
+                return Object.assign(Object.assign({}, base), { bottom: 20, right: 20 });
+            default:
+                return Object.assign(Object.assign({}, base), { top: 20, left: '50%', transform: 'translateX(-50%)' });
+        }
+    };
+    const containerStyles = Object.assign(Object.assign({}, getPositionStyles()), { background: themeStyles.background, borderRadius: themeStyles.borderRadius, boxShadow: themeStyles.boxShadow, padding: '16px 24px', minWidth: '320px', maxWidth: '500px', display: 'flex', alignItems: 'center', gap: '16px', opacity: isVisible && !isExiting ? 1 : 0, transform: position.startsWith('top')
+            ? `translateY(${isVisible && !isExiting ? '0' : '-20px'}) ${position.includes('center') ? 'translateX(-50%)' : ''}`
+            : `translateY(${isVisible && !isExiting ? '0' : '20px'}) ${position.includes('center') ? 'translateX(-50%)' : ''}`, transition: 'all 0.3s cubic-bezier(0.4, 0, 0.2, 1)', pointerEvents: isVisible ? 'auto' : 'none' });
+    const iconStyles = {
+        fontSize: '48px',
+        lineHeight: 1,
+        flexShrink: 0,
+    };
+    const contentStyles = {
+        flex: 1,
+        color: themeStyles.textColor,
+        minWidth: 0,
+    };
+    const headerStyles = {
+        fontSize: ((_a = themeStyles.fontSize) === null || _a === void 0 ? void 0 : _a.header) || '12px',
+        textTransform: 'uppercase',
+        letterSpacing: '1px',
+        opacity: 0.8,
+        marginBottom: '4px',
+        color: themeStyles.accentColor,
+        fontWeight: 600,
+    };
+    const titleStyles = {
+        fontSize: ((_b = themeStyles.fontSize) === null || _b === void 0 ? void 0 : _b.title) || '18px',
+        fontWeight: 'bold',
+        marginBottom: '4px',
+        overflow: 'hidden',
+        textOverflow: 'ellipsis',
+        whiteSpace: 'nowrap',
+    };
+    const descriptionStyles = {
+        fontSize: ((_c = themeStyles.fontSize) === null || _c === void 0 ? void 0 : _c.description) || '14px',
+        opacity: 0.9,
+        overflow: 'hidden',
+        textOverflow: 'ellipsis',
+        display: '-webkit-box',
+        WebkitLineClamp: 2,
+        WebkitBoxOrient: 'vertical',
+    };
+    const closeButtonStyles = {
+        background: 'none',
+        border: 'none',
+        color: themeStyles.textColor,
+        fontSize: '24px',
+        cursor: 'pointer',
+        opacity: 0.6,
+        transition: 'opacity 0.2s',
+        padding: '4px',
+        flexShrink: 0,
+        lineHeight: 1,
+    };
+    // If achievementIconKey exists but not in mergedIcons, use it directly (might be an emoji)
+    // Otherwise, look up in mergedIcons or fall back to default
+    const icon = (achievement.achievementIconKey &&
+        mergedIcons[achievement.achievementIconKey]) ||
+        achievement.achievementIconKey ||
+        mergedIcons.default ||
+        '⭐';
+    return (React.createElement("div", { style: containerStyles, "data-testid": "built-in-notification" },
+        React.createElement("div", { style: iconStyles }, icon),
+        React.createElement("div", { style: contentStyles },
+            React.createElement("div", { style: headerStyles }, "Achievement Unlocked!"),
+            React.createElement("div", { style: titleStyles }, achievement.achievementTitle),
+            achievement.achievementDescription && (React.createElement("div", { style: descriptionStyles }, achievement.achievementDescription))),
+        React.createElement("button", { onClick: () => {
+                setIsExiting(true);
+                setTimeout(() => onClose === null || onClose === void 0 ? void 0 : onClose(), 300);
+            }, style: closeButtonStyles, onMouseEnter: (e) => (e.currentTarget.style.opacity = '1'), onMouseLeave: (e) => (e.currentTarget.style.opacity = '0.6'), "aria-label": "Close notification" }, "\u00D7")));
+};
+
+/**
+ * Built-in confetti component
+ * Lightweight CSS-based confetti animation
+ */
+const BuiltInConfetti = ({ show, duration = 5000, particleCount = 50, colors = ['#FFD700', '#FF6B6B', '#4ECDC4', '#45B7D1', '#96CEB4', '#FFEAA7'], }) => {
+    const [isVisible, setIsVisible] = useState(false);
+    const { width, height } = useWindowSize();
+    useEffect(() => {
+        if (show) {
+            setIsVisible(true);
+            const timer = setTimeout(() => setIsVisible(false), duration);
+            return () => clearTimeout(timer);
+        }
+        else {
+            setIsVisible(false);
+        }
+    }, [show, duration]);
+    if (!isVisible)
+        return null;
+    const containerStyles = {
+        position: 'fixed',
+        top: 0,
+        left: 0,
+        width: '100%',
+        height: '100%',
+        pointerEvents: 'none',
+        zIndex: 10001,
+        overflow: 'hidden',
+    };
+    // Generate particles
+    const particles = Array.from({ length: particleCount }, (_, i) => {
+        const color = colors[Math.floor(Math.random() * colors.length)];
+        const startX = Math.random() * width;
+        const rotation = Math.random() * 360;
+        const fallDuration = 3 + Math.random() * 2; // 3-5 seconds
+        const delay = Math.random() * 0.5; // 0-0.5s delay
+        const shape = Math.random() > 0.5 ? 'circle' : 'square';
+        const particleStyles = {
+            position: 'absolute',
+            top: '-20px',
+            left: `${startX}px`,
+            width: '10px',
+            height: '10px',
+            backgroundColor: color,
+            borderRadius: shape === 'circle' ? '50%' : '0',
+            transform: `rotate(${rotation}deg)`,
+            animation: `confettiFall ${fallDuration}s linear ${delay}s forwards`,
+            opacity: 0.9,
+        };
+        return React.createElement("div", { key: i, style: particleStyles, "data-testid": "confetti-particle" });
+    });
+    return (React.createElement(React.Fragment, null,
+        React.createElement("style", null, `
+          @keyframes confettiFall {
+            0% {
+              transform: translateY(0) rotate(0deg);
+              opacity: 1;
+            }
+            100% {
+              transform: translateY(${height + 50}px) rotate(720deg);
+              opacity: 0;
+            }
+          }
+        `),
+        React.createElement("div", { style: containerStyles, "data-testid": "built-in-confetti" }, particles)));
+};
+
+/******************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+/* global Reflect, Promise, SuppressedError, Symbol, Iterator */
+
+
+function __awaiter(thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+}
+
+typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
+/**
+ * Legacy UI library detection system
+ * Attempts to dynamically import external UI libraries
+ * Shows deprecation warnings when detected
+ */
+let cachedLibraries = null;
+let detectionAttempted = false;
+let deprecationWarningShown = false;
+/**
+ * Attempts to dynamically import legacy UI libraries
+ * Uses try/catch to gracefully handle missing dependencies
+ * Caches result to avoid multiple import attempts
+ *
+ * @returns Promise resolving to LegacyLibraries object
+ */
+function detectLegacyLibraries() {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (detectionAttempted && cachedLibraries !== null) {
+            return cachedLibraries;
+        }
+        detectionAttempted = true;
+        const libraries = {};
+        // Try to import react-toastify
+        try {
+            const toastifyModule = yield import('react-toastify');
+            libraries.toast = toastifyModule.toast;
+            libraries.ToastContainer = toastifyModule.ToastContainer;
+        }
+        catch (_a) {
+            // Not installed, will use built-in notification
+        }
+        // Try to import react-modal
+        try {
+            const modalModule = yield import('react-modal');
+            libraries.Modal = modalModule.default;
+        }
+        catch (_b) {
+            // Not installed, will use built-in modal
+        }
+        // Try to import react-confetti
+        try {
+            const confettiModule = yield import('react-confetti');
+            libraries.Confetti = confettiModule.default;
+        }
+        catch (_c) {
+            // Not installed, will use built-in confetti
+        }
+        // Try to import react-use (only for useWindowSize)
+        try {
+            const reactUseModule = yield import('react-use');
+            libraries.useWindowSize = reactUseModule.useWindowSize;
+        }
+        catch (_d) {
+            // Not installed, will use built-in useWindowSize
+        }
+        cachedLibraries = libraries;
+        // Show deprecation warning if ANY legacy library is found
+        if (!deprecationWarningShown && Object.keys(libraries).length > 0) {
+            const foundLibraries = [];
+            if (libraries.toast)
+                foundLibraries.push('react-toastify');
+            if (libraries.Modal)
+                foundLibraries.push('react-modal');
+            if (libraries.Confetti)
+                foundLibraries.push('react-confetti');
+            if (libraries.useWindowSize)
+                foundLibraries.push('react-use');
+            console.warn(`[react-achievements] DEPRECATION WARNING: External UI dependencies (${foundLibraries.join(', ')}) are deprecated and will become fully optional in v4.0.0.\n\n` +
+                `The library now includes built-in UI components with modern design and theme support.\n\n` +
+                `To migrate:\n` +
+                `1. Add "useBuiltInUI={true}" to your AchievementProvider\n` +
+                `2. Test your application (UI will change to modern theme)\n` +
+                `3. Optionally customize with theme="minimal" or theme="gamified"\n` +
+                `4. Remove external dependencies from package.json\n\n` +
+                `To silence this warning, set useBuiltInUI={true} in AchievementProvider.\n\n` +
+                `Learn more: https://github.com/dave-b-b/react-achievements#migration-guide`);
+            deprecationWarningShown = true;
+        }
+        return libraries;
+    });
+}
+
+/**
+ * Built-in modal component
+ * Modern, theme-aware achievement modal with smooth animations
+ */
+const BuiltInModal = ({ isOpen, onClose, achievements, icons = {}, theme = 'modern', }) => {
+    // Merge custom icons with defaults
+    const mergedIcons = Object.assign(Object.assign({}, defaultAchievementIcons), icons);
+    // Get theme configuration
+    const themeConfig = getTheme(theme) || builtInThemes.modern;
+    const { modal: themeStyles } = themeConfig;
+    useEffect(() => {
+        if (isOpen) {
+            // Lock body scroll when modal is open
+            document.body.style.overflow = 'hidden';
+        }
+        else {
+            // Restore body scroll
+            document.body.style.overflow = '';
+        }
+        return () => {
+            document.body.style.overflow = '';
+        };
+    }, [isOpen]);
+    if (!isOpen)
+        return null;
+    const overlayStyles = {
+        position: 'fixed',
+        top: 0,
+        left: 0,
+        right: 0,
+        bottom: 0,
+        backgroundColor: themeStyles.overlayColor,
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        zIndex: 10000,
+        animation: 'fadeIn 0.3s ease-in-out',
+    };
+    const modalStyles = {
+        background: themeStyles.background,
+        borderRadius: themeStyles.borderRadius,
+        padding: '32px',
+        maxWidth: '600px',
+        width: '90%',
+        maxHeight: '80vh',
+        overflow: 'auto',
+        boxShadow: '0 20px 60px rgba(0, 0, 0, 0.5)',
+        animation: 'scaleIn 0.3s cubic-bezier(0.4, 0, 0.2, 1)',
+        position: 'relative',
+    };
+    const headerStyles = {
+        display: 'flex',
+        justifyContent: 'space-between',
+        alignItems: 'center',
+        marginBottom: '24px',
+    };
+    const titleStyles = {
+        margin: 0,
+        color: themeStyles.textColor,
+        fontSize: themeStyles.headerFontSize || '28px',
+        fontWeight: 'bold',
+    };
+    const closeButtonStyles = {
+        background: 'none',
+        border: 'none',
+        fontSize: '32px',
+        cursor: 'pointer',
+        color: themeStyles.textColor,
+        opacity: 0.6,
+        transition: 'opacity 0.2s',
+        padding: 0,
+        lineHeight: 1,
+    };
+    const isBadgeLayout = themeStyles.achievementLayout === 'badge';
+    const listStyles = isBadgeLayout
+        ? {
+            display: 'grid',
+            gridTemplateColumns: 'repeat(auto-fill, minmax(140px, 1fr))',
+            gap: '16px',
+        }
+        : {
+            display: 'flex',
+            flexDirection: 'column',
+            gap: '12px',
+        };
+    const getAchievementItemStyles = (isUnlocked) => {
+        const baseStyles = {
+            borderRadius: themeStyles.achievementCardBorderRadius || '12px',
+            backgroundColor: isUnlocked
+                ? `${themeStyles.accentColor}1A` // 10% opacity
+                : 'rgba(255, 255, 255, 0.05)',
+            border: `2px solid ${isUnlocked ? themeStyles.accentColor : 'rgba(255, 255, 255, 0.1)'}`,
+            opacity: isUnlocked ? 1 : 0.5,
+            transition: 'all 0.2s',
+        };
+        if (isBadgeLayout) {
+            // Badge layout: vertical, centered, square-ish
+            return Object.assign(Object.assign({}, baseStyles), { display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center', textAlign: 'center', padding: '20px 12px', aspectRatio: '1 / 1.1', minHeight: '160px' });
+        }
+        else {
+            // Horizontal layout (default)
+            return Object.assign(Object.assign({}, baseStyles), { display: 'flex', gap: '16px', padding: '16px' });
+        }
+    };
+    const getIconContainerStyles = (isUnlocked) => {
+        if (isBadgeLayout) {
+            return {
+                fontSize: '48px',
+                lineHeight: 1,
+                marginBottom: '8px',
+                opacity: isUnlocked ? 1 : 0.3,
+            };
+        }
+        return {
+            fontSize: '40px',
+            flexShrink: 0,
+            lineHeight: 1,
+            opacity: isUnlocked ? 1 : 0.3,
+        };
+    };
+    const contentStyles = isBadgeLayout
+        ? {
+            width: '100%',
+        }
+        : {
+            flex: 1,
+            minWidth: 0,
+        };
+    const achievementTitleStyles = isBadgeLayout
+        ? {
+            margin: '0 0 4px 0',
+            color: themeStyles.textColor,
+            fontSize: '14px',
+            fontWeight: 'bold',
+            lineHeight: '1.3',
+        }
+        : {
+            margin: '0 0 8px 0',
+            color: themeStyles.textColor,
+            fontSize: '18px',
+            fontWeight: 'bold',
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            whiteSpace: 'nowrap',
+        };
+    const achievementDescriptionStyles = isBadgeLayout
+        ? {
+            margin: 0,
+            color: themeStyles.textColor,
+            opacity: 0.7,
+            fontSize: '11px',
+            lineHeight: '1.3',
+        }
+        : {
+            margin: 0,
+            color: themeStyles.textColor,
+            opacity: 0.8,
+            fontSize: '14px',
+        };
+    const getLockIconStyles = () => {
+        if (isBadgeLayout) {
+            return {
+                position: 'absolute',
+                top: '8px',
+                right: '8px',
+                fontSize: '18px',
+                opacity: 0.6,
+            };
+        }
+        return {
+            fontSize: '24px',
+            flexShrink: 0,
+            opacity: 0.5,
+        };
+    };
+    return (React.createElement(React.Fragment, null,
+        React.createElement("style", null, `
+          @keyframes fadeIn {
+            from { opacity: 0; }
+            to { opacity: 1; }
+          }
+          @keyframes scaleIn {
+            from {
+              transform: scale(0.9);
+              opacity: 0;
+            }
+            to {
+              transform: scale(1);
+              opacity: 1;
+            }
+          }
+        `),
+        React.createElement("div", { style: overlayStyles, onClick: onClose, "data-testid": "built-in-modal-overlay" },
+            React.createElement("div", { style: modalStyles, onClick: (e) => e.stopPropagation(), "data-testid": "built-in-modal" },
+                React.createElement("div", { style: headerStyles },
+                    React.createElement("h2", { style: titleStyles }, "\uD83C\uDFC6 Achievements"),
+                    React.createElement("button", { onClick: onClose, style: closeButtonStyles, onMouseEnter: (e) => (e.currentTarget.style.opacity = '1'), onMouseLeave: (e) => (e.currentTarget.style.opacity = '0.6'), "aria-label": "Close modal" }, "\u00D7")),
+                React.createElement("div", { style: listStyles }, achievements.length === 0 ? (React.createElement("div", { style: { textAlign: 'center', padding: '40px 20px', color: themeStyles.textColor, opacity: 0.6 } }, "No achievements yet. Start exploring to unlock them!")) : (achievements.map((achievement) => {
+                    // If achievementIconKey exists but not in mergedIcons, use it directly (might be an emoji)
+                    // Otherwise, look up in mergedIcons or fall back to default
+                    const icon = (achievement.achievementIconKey &&
+                        mergedIcons[achievement.achievementIconKey]) ||
+                        achievement.achievementIconKey ||
+                        mergedIcons.default ||
+                        '⭐';
+                    return (React.createElement("div", { key: achievement.achievementId, style: Object.assign(Object.assign({}, getAchievementItemStyles(achievement.isUnlocked)), { position: isBadgeLayout ? 'relative' : 'static' }) },
+                        React.createElement("div", { style: getIconContainerStyles(achievement.isUnlocked) }, icon),
+                        React.createElement("div", { style: contentStyles },
+                            React.createElement("h3", { style: achievementTitleStyles }, achievement.achievementTitle),
+                            React.createElement("p", { style: achievementDescriptionStyles }, achievement.achievementDescription)),
+                        !achievement.isUnlocked && (React.createElement("div", { style: getLockIconStyles() }, "\uD83D\uDD12"))));
+                })))))));
+};
+
+/**
+ * Legacy library wrappers for backwards compatibility
+ * Wraps external UI libraries to match our component interfaces
+ */
+/**
+ * Wrapper for react-toastify toast notifications
+ * Falls back to built-in notification if not available
+ */
+const createLegacyToastNotification = (libraries) => {
+    return ({ achievement, onClose, icons = {} }) => {
+        const { toast } = libraries;
+        //  Merge custom icons with defaults from react-achievements
+        const mergedIcons = Object.assign(Object.assign({}, defaultAchievementIcons), icons);
+        const icon = (achievement.achievementIconKey &&
+            mergedIcons[achievement.achievementIconKey]) ||
+            achievement.achievementIconKey ||
+            mergedIcons.default ||
+            '⭐';
+        useEffect(() => {
+            if (!toast)
+                return;
+            // Call toast.success with achievement content
+            toast.success(React.createElement("div", { style: { display: 'flex', alignItems: 'center' } },
+                React.createElement("span", { style: { fontSize: '2em', marginRight: '10px' } }, icon),
+                React.createElement("div", null,
+                    React.createElement("div", { style: { fontSize: '12px', opacity: 0.8, marginBottom: '4px' } }, "Achievement Unlocked!"),
+                    React.createElement("div", { style: { fontWeight: 'bold', marginBottom: '4px' } }, achievement.achievementTitle),
+                    achievement.achievementDescription && (React.createElement("div", { style: { fontSize: '13px', opacity: 0.9 } }, achievement.achievementDescription)))), {
+                position: 'top-right',
+                autoClose: 5000,
+                hideProgressBar: false,
+                closeOnClick: true,
+                pauseOnHover: true,
+                draggable: true,
+                toastId: achievement.achievementId,
+                onClose,
+            });
+        }, [achievement, toast, onClose, icon]);
+        return null; // Toast handles its own rendering
+    };
+};
+/**
+ * Wrapper for react-confetti Confetti component
+ * Falls back to built-in confetti if not available
+ */
+const createLegacyConfettiWrapper = (libraries) => {
+    return ({ show, duration = 5000, particleCount = 200, colors }) => {
+        const { Confetti, useWindowSize: legacyUseWindowSize } = libraries;
+        // If Confetti not available, use built-in
+        if (!Confetti) {
+            return (React.createElement(BuiltInConfetti, { show: show, duration: duration, particleCount: particleCount, colors: colors }));
+        }
+        // Use react-confetti with react-use's useWindowSize if available
+        // Otherwise fall back to default dimensions
+        let width = 0;
+        let height = 0;
+        if (legacyUseWindowSize) {
+            const size = legacyUseWindowSize();
+            width = size.width;
+            height = size.height;
+        }
+        else if (typeof window !== 'undefined') {
+            width = window.innerWidth;
+            height = window.innerHeight;
+        }
+        if (!show)
+            return null;
+        return (React.createElement(Confetti, { width: width, height: height, numberOfPieces: particleCount, recycle: false, colors: colors, style: {
+                position: 'fixed',
+                top: 0,
+                left: 0,
+                zIndex: 10001,
+                pointerEvents: 'none',
+            } }));
+    };
+};
+
+const AchievementContext = createContext(undefined);
+const AchievementProvider = ({ achievements: achievementsConfig, storage = 'local', children, icons = {}, onError, restApiConfig, ui = {}, useBuiltInUI = false, engine: externalEngine, eventMapping, }) => {
+    // VALIDATION: Prevent mixing patterns
+    if (achievementsConfig && externalEngine) {
+        throw new Error('Cannot provide both "achievements" and "engine" props to AchievementProvider.\n\n' +
+            'Choose one pattern:\n' +
+            '1. OLD metric-based: <AchievementProvider achievements={config}>\n' +
+            '2. NEW event-based: <AchievementProvider engine={myEngine}>');
+    }
+    // Track which pattern is being used
+    const isLegacyPattern = Boolean(achievementsConfig);
+    // Engine instance (either external or auto-created)
+    // Initialize synchronously BEFORE first render to avoid timing issues
+    const [engine] = useState(() => {
+        if (externalEngine) {
+            // NEW PATTERN: Use external injected engine
+            return externalEngine;
+        }
+        // OLD PATTERN: Auto-create engine from achievements
+        if (!achievementsConfig) {
+            throw new Error('AchievementProvider requires either "achievements" or "engine" prop.\n\n' +
+                '1. OLD pattern: <AchievementProvider achievements={config}>\n' +
+                '2. NEW pattern: <AchievementProvider engine={myEngine}>');
+        }
+        return new AchievementEngine({
+            achievements: achievementsConfig,
+            storage: storage, // Type cast needed for compatibility
+            restApiConfig,
+            onError: onError,
+            eventMapping,
+        });
+    });
+    // React state synced from engine
+    // Initialize with current engine state (engine is available immediately)
+    const [achievementState, setAchievementState] = useState(() => {
+        const unlocked = engine.getUnlocked();
+        return {
+            unlocked: [...unlocked],
+            all: {}, // Will be populated by getAllAchievements
+        };
+    });
+    // Track which achievements have been seen to avoid duplicate notifications
+    const seenAchievementsRef = useRef(new Set(engine.getUnlocked()));
+    const [showConfetti, setShowConfetti] = useState(false);
+    // NEW: UI component resolution state (v3.6.0)
+    const [legacyLibraries, setLegacyLibraries] = useState(null);
+    const [uiReady, setUiReady] = useState(useBuiltInUI);
+    const [currentNotification, setCurrentNotification] = useState(null);
+    // Cleanup: Destroy engine on unmount (only if we auto-created it)
+    useEffect(() => {
+        return () => {
+            // Only destroy if we auto-created the engine
+            if (!externalEngine) {
+                engine.destroy();
+            }
+        };
+    }, [engine, externalEngine]);
+    // Subscribe to engine events
+    useEffect(() => {
+        // Engine is always available (initialized synchronously)
+        // Handle achievement unlocked
+        const unsubscribeUnlocked = engine.on('achievement:unlocked', (event) => {
+            // Update unlocked list
+            setAchievementState(prev => (Object.assign(Object.assign({}, prev), { unlocked: [...engine.getUnlocked()] })));
+            // Show notification if not seen before
+            if (!seenAchievementsRef.current.has(event.achievementId)) {
+                seenAchievementsRef.current.add(event.achievementId);
+                if (ui.enableNotifications !== false) {
+                    // Create a full AchievementWithStatus object for the notification
+                    const unlockedAchievement = {
+                        achievementId: event.achievementId,
+                        achievementTitle: event.achievementTitle,
+                        achievementDescription: event.achievementDescription,
+                        achievementIconKey: event.achievementIconKey,
+                        isUnlocked: true,
+                    };
+                    setCurrentNotification(unlockedAchievement);
+                    // Show confetti
+                    setShowConfetti(true);
+                    // Hide confetti after 5 seconds
+                    setTimeout(() => {
+                        setShowConfetti(false);
+                    }, 5000);
+                }
+            }
+        });
+        // Handle state changes (for syncing unlocked list)
+        const unsubscribeStateChanged = engine.on('state:changed', () => {
+            setAchievementState(prev => (Object.assign(Object.assign({}, prev), { unlocked: [...engine.getUnlocked()] })));
+        });
+        return () => {
+            unsubscribeUnlocked();
+            unsubscribeStateChanged();
+        };
+    }, [engine, icons, ui.enableNotifications]);
+    // Detect legacy UI libraries on mount
+    useEffect(() => {
+        if (useBuiltInUI) {
+            setUiReady(true);
+            return;
+        }
+        detectLegacyLibraries().then((libs) => {
+            setLegacyLibraries(libs);
+            setUiReady(true);
+        });
+    }, [useBuiltInUI]);
+    // Resolve UI components based on detection and config
+    const NotificationComponent = ui.NotificationComponent ||
+        (useBuiltInUI ? BuiltInNotification :
+            legacyLibraries && Object.keys(legacyLibraries).length > 0 && legacyLibraries.toast
+                ? createLegacyToastNotification(legacyLibraries)
+                : BuiltInNotification);
+    const ConfettiComponentResolved = ui.ConfettiComponent ||
+        (useBuiltInUI ? BuiltInConfetti :
+            legacyLibraries && Object.keys(legacyLibraries).length > 0 && legacyLibraries.Confetti
+                ? createLegacyConfettiWrapper(legacyLibraries)
+                : BuiltInConfetti);
+    // Context methods - delegate to engine
+    const update = (newMetrics) => {
+        engine.update(newMetrics);
+    };
+    const reset = () => {
+        engine.reset();
+        seenAchievementsRef.current.clear();
+        setShowConfetti(false);
+        setCurrentNotification(null);
+    };
+    const getState = () => {
+        const metrics = engine.getMetrics();
+        const unlocked = engine.getUnlocked();
+        // Convert metrics to array format for backward compatibility
+        const metricsInArrayFormat = {};
+        Object.entries(metrics).forEach(([key, value]) => {
+            metricsInArrayFormat[key] = Array.isArray(value) ? value : [value];
+        });
+        return {
+            metrics: metricsInArrayFormat,
+            unlocked: [...unlocked],
+        };
+    };
+    const exportData = () => {
+        return engine.export();
+    };
+    const importData = (jsonString, options) => {
+        var _a;
+        const result = engine.import(jsonString, options);
+        // Update seen achievements to prevent duplicate notifications
+        if ((result === null || result === void 0 ? void 0 : result.success) && 'mergedUnlocked' in result) {
+            (_a = result.mergedUnlocked) === null || _a === void 0 ? void 0 : _a.forEach((id) => {
+                seenAchievementsRef.current.add(id);
+            });
+        }
+        return result;
+    };
+    const getAllAchievements = () => {
+        return engine.getAllAchievements();
+    };
+    return (React.createElement(AchievementContext.Provider, { value: {
+            update,
+            achievements: achievementState,
+            reset,
+            getState,
+            exportData,
+            importData,
+            getAllAchievements,
+            engine, // Always defined - no undefined fallback needed
+            _isLegacyPattern: isLegacyPattern, // NEW: Expose pattern flag to hooks
+        } },
+        children,
+        uiReady && currentNotification && ui.enableNotifications !== false && (React.createElement(NotificationComponent, { achievement: currentNotification, onClose: () => setCurrentNotification(null), duration: 5000, position: ui.notificationPosition || 'top-center', theme: ui.theme || 'modern', icons: icons })),
+        uiReady && ui.enableConfetti !== false && (React.createElement(ConfettiComponentResolved, { show: showConfetti, duration: 5000 }))));
+};
+
+const useAchievements = () => {
+    const context = useContext(AchievementContext);
+    if (!context) {
+        throw new Error('useAchievements must be used within an AchievementProvider');
+    }
+    // STRICT CHECK: Detect if Provider has injected engine (new pattern)
+    if (!context._isLegacyPattern) {
+        throw new Error('Cannot use useAchievements when AchievementProvider has injected engine.\n\n' +
+            'You are using the NEW event-based pattern.\n' +
+            'useAchievements is for the OLD metric-based pattern only.\n\n' +
+            'Use engine.emit() instead:\n' +
+            '  const engine = useAchievementEngine();\n' +
+            '  engine.emit("eventName", data);\n\n' +
+            'Or switch to the old pattern:\n' +
+            '  <AchievementProvider achievements={config}>\n' +
+            '  const { track } = useAchievements();\n' +
+            '  track("score", 100);');
+    }
+    return context;
+};
+
+/**
+ * A simplified hook for achievement tracking.
+ * Provides an easier API for common use cases while maintaining access to advanced features.
+ */
+const useSimpleAchievements = () => {
+    const { update, achievements, reset, getState, exportData, importData, getAllAchievements } = useAchievements();
+    return {
+        /**
+         * Track a metric value for achievements
+         * @param metric - The metric name (e.g., 'score', 'level')
+         * @param value - The metric value
+         */
+        track: (metric, value) => update({ [metric]: value }),
+        /**
+         * Increment a numeric metric by a specified amount
+         * @param metric - The metric name (e.g., 'buttonClicks', 'score')
+         * @param amount - The amount to increment by (defaults to 1)
+         */
+        increment: (metric, amount = 1) => {
+            const currentState = getState();
+            const currentMetricArray = currentState.metrics[metric] || [0];
+            const currentValue = Array.isArray(currentMetricArray) ? currentMetricArray[0] : currentMetricArray;
+            const newValue = (typeof currentValue === 'number' ? currentValue : 0) + amount;
+            update({ [metric]: newValue });
+        },
+        /**
+         * Track multiple metrics at once
+         * @param metrics - Object with metric names as keys and values
+         */
+        trackMultiple: (metrics) => update(metrics),
+        /**
+         * Array of unlocked achievement IDs
+         */
+        unlocked: achievements.unlocked,
+        /**
+         * All available achievements
+         */
+        all: achievements.all,
+        /**
+         * Number of unlocked achievements
+         */
+        unlockedCount: achievements.unlocked.length,
+        /**
+         * Reset all achievement progress
+         */
+        reset,
+        /**
+         * Get current state (advanced usage)
+         */
+        getState,
+        /**
+         * Export achievement data to JSON string
+         * @returns JSON string containing all achievement data
+         */
+        exportData,
+        /**
+         * Import achievement data from JSON string
+         * @param jsonString - JSON string containing exported achievement data
+         * @param options - Import options (merge strategy, validation)
+         * @returns Import result with success status and any errors
+         */
+        importData,
+        /**
+         * Get all achievements with their unlock status
+         * @returns Array of achievements with isUnlocked boolean property
+         */
+        getAllAchievements,
+    };
+};
+
+/**
+ * Hook to access the injected AchievementEngine instance (NEW event-based pattern)
+ *
+ * IMPORTANT: This hook only works when Provider has an externally created engine injected via the `engine` prop.
+ * Do NOT use this hook with the old `achievements` prop pattern - use `useAchievements()` instead.
+ *
+ * @example
+ * ```tsx
+ * // Create engine outside React
+ * import { AchievementEngine } from 'achievements-engine';
+ *
+ * const myEngine = new AchievementEngine({
+ *   achievements: config,
+ *   eventMapping: { 'userScored': 'score', 'levelUp': 'level' },
+ *   storage: 'local'
+ * });
+ *
+ * // Inject into Provider
+ * <AchievementProvider engine={myEngine}>
+ *   <App />
+ * </AchievementProvider>
+ *
+ * function App() {
+ *   const engine = useAchievementEngine();
+ *   engine.emit('userScored', 100);
+ *   engine.emit('levelUp', 5);
+ * }
+ * ```
+ *
+ * @returns AchievementEngine instance
+ * @throws Error if used with old achievements prop pattern
+ * @throws Error if used outside AchievementProvider
+ * @since 3.8.0
+ */
+const useAchievementEngine = () => {
+    const context = useContext(AchievementContext);
+    if (!context) {
+        throw new Error('useAchievementEngine must be used within an AchievementProvider.\n\n' +
+            'Wrap your component tree:\n' +
+            'const myEngine = new AchievementEngine({ achievements, eventMapping });\n' +
+            '<AchievementProvider engine={myEngine}>\n' +
+            '  <YourComponent />\n' +
+            '</AchievementProvider>');
+    }
+    // STRICT CHECK: Detect if Provider was initialized with achievements (old pattern)
+    if (context._isLegacyPattern) {
+        throw new Error('Cannot use useAchievementEngine when AchievementProvider has achievements prop.\n\n' +
+            'You are using the OLD metric-based pattern.\n' +
+            'useAchievementEngine is for the NEW event-based pattern only.\n\n' +
+            'Choose one:\n\n' +
+            '1. OLD PATTERN (keep current code):\n' +
+            '   <AchievementProvider achievements={config}>\n' +
+            '   const { track } = useAchievements();\n' +
+            '   track("score", 100);\n\n' +
+            '2. NEW PATTERN (migrate to events):\n' +
+            '   const engine = new AchievementEngine({ achievements, eventMapping });\n' +
+            '   <AchievementProvider engine={engine}>\n' +
+            '   const engine = useAchievementEngine();\n' +
+            '   engine.emit("userScored", 100);');
+    }
+    if (!context.engine) {
+        throw new Error('No engine available. AchievementProvider requires either:\n' +
+            '1. achievements prop (old pattern)\n' +
+            '2. engine prop (new pattern)');
+    }
+    return context.engine;
+};
+
+export { AchievementContext, AchievementProvider, BadgesButton, BadgesButtonWithModal, BadgesModal, BuiltInConfetti, BuiltInModal, BuiltInNotification, ConfettiWrapper, defaultAchievementIcons, defaultStyles, isAsyncStorage, useAchievementEngine, useAchievements, useSimpleAchievements, useWindowSize };
+//# sourceMappingURL=index.esm.js.map