react-achievements 4.3.0 → 4.4.0

package/dist/index.esm.js

@@ -1,6 +1,7 @@
-import { AchievementEngine } from 'achievements-engine';
+import { AchievementEngine, isSimpleConfig, normalizeAchievements } 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, { createContext, useState, useCallback, useEffect, useContext, useRef, useMemo } from 'react';
+import confetti from 'canvas-confetti';
 
 // Type guard to detect async storage
 function isAsyncStorage(storage) {
@@ -213,7 +214,7 @@ const builtInThemes = {
         },
         confetti: {
             colors: ['#FFD700', '#4CAF50', '#2196F3', '#FF6B6B'],
-            particleCount: 50,
+            particleCount: 80,
             shapes: ['circle', 'square'],
         },
     },
@@ -245,7 +246,7 @@ const builtInThemes = {
         },
         confetti: {
             colors: ['#4CAF50', '#2196F3'],
-            particleCount: 30,
+            particleCount: 40,
             shapes: ['circle'],
         },
     },
@@ -280,7 +281,7 @@ const builtInThemes = {
         },
         confetti: {
             colors: ['#22d3ee', '#f97316', '#a855f7', '#eab308'], // Cyan, orange, purple, yellow
-            particleCount: 100,
+            particleCount: 120,
             shapes: ['circle', 'square'],
         },
     },
@@ -436,129 +437,159 @@ const BuiltInNotification = ({ achievement, onClose, duration = 5000, position =
         React.createElement("button", { onClick: closeAfterExit, style: closeButtonStyles, onMouseEnter: (e) => (e.currentTarget.style.opacity = '1'), onMouseLeave: (e) => (e.currentTarget.style.opacity = '0.6'), "aria-label": "Close notification" }, "\u00D7")));
 };
 
+const DEFAULT_COLORS = ['#FFD700', '#FF6B6B', '#4ECDC4', '#45B7D1', '#96CEB4', '#FFEAA7'];
+const DEFAULT_DURATION_MS = 5000;
+const DEFAULT_PARTICLE_COUNT = 80;
+const DEFAULT_SHAPES = ['square', 'circle'];
+const DEFAULT_SPREAD = 70;
+const DEFAULT_START_VELOCITY = 45;
+const DEFAULT_GRAVITY = 1;
+const DEFAULT_SCALAR = 1;
+const DEFAULT_Z_INDEX = 10001;
+const getSafeParticleCount = (count) => Math.max(0, Math.floor(count));
 /**
- * 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}`);
- * ```
+ * Built-in confetti component
+ * Canvas-based confetti animation powered by canvas-confetti.
  */
-function useWindowSize() {
-    const [size, setSize] = useState({
-        width: typeof window !== 'undefined' ? window.innerWidth : 0,
-        height: typeof window !== 'undefined' ? window.innerHeight : 0,
-    });
+const BuiltInConfetti = ({ show, duration = DEFAULT_DURATION_MS, particleCount = DEFAULT_PARTICLE_COUNT, colors = DEFAULT_COLORS, shapes = DEFAULT_SHAPES, spread = DEFAULT_SPREAD, startVelocity = DEFAULT_START_VELOCITY, gravity = DEFAULT_GRAVITY, scalar = DEFAULT_SCALAR, zIndex = DEFAULT_Z_INDEX, }) => {
+    const [isVisible, setIsVisible] = useState(false);
     useEffect(() => {
-        // Handle SSR - window may not be defined
-        if (typeof window === 'undefined') {
+        if (!show) {
+            setIsVisible(false);
+            confetti.reset();
             return;
         }
-        const handleResize = () => {
-            setSize({
-                width: window.innerWidth,
-                height: window.innerHeight,
-            });
+        setIsVisible(true);
+        const totalParticles = getSafeParticleCount(particleCount);
+        const resolvedColors = colors.length > 0 ? colors : DEFAULT_COLORS;
+        const resolvedShapes = shapes.length > 0 ? shapes : DEFAULT_SHAPES;
+        const baseOptions = {
+            colors: resolvedColors,
+            shapes: resolvedShapes,
+            spread,
+            startVelocity,
+            gravity,
+            scalar,
+            zIndex,
+            disableForReducedMotion: true,
         };
-        // Set initial size
-        handleResize();
-        // Add event listener
-        window.addEventListener('resize', handleResize);
-        // Cleanup
-        return () => {
-            window.removeEventListener('resize', handleResize);
-        };
-    }, []);
-    return size;
-}
-
-/**
- * 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);
+        if (totalParticles > 0) {
+            const centerParticles = Math.ceil(totalParticles * 0.5);
+            const leftParticles = Math.floor((totalParticles - centerParticles) / 2);
+            const rightParticles = totalParticles - centerParticles - leftParticles;
+            confetti(Object.assign(Object.assign({}, baseOptions), { particleCount: centerParticles, origin: { x: 0.5, y: 0.58 } }));
+            confetti(Object.assign(Object.assign({}, baseOptions), { particleCount: leftParticles, angle: 60, spread: Math.max(45, spread * 0.8), origin: { x: 0, y: 0.72 } }));
+            confetti(Object.assign(Object.assign({}, baseOptions), { particleCount: rightParticles, angle: 120, spread: Math.max(45, spread * 0.8), origin: { x: 1, y: 0.72 } }));
         }
-        else {
+        const timer = setTimeout(() => {
             setIsVisible(false);
-        }
-    }, [show, duration]);
+            confetti.reset();
+        }, duration);
+        return () => {
+            clearTimeout(timer);
+            confetti.reset();
+        };
+    }, [
+        show,
+        duration,
+        particleCount,
+        colors,
+        shapes,
+        spread,
+        startVelocity,
+        gravity,
+        scalar,
+        zIndex,
+    ]);
     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)));
+    return React.createElement("div", { "data-testid": "built-in-confetti", style: { display: 'none' } });
 };
 
 const DEFAULT_NOTIFICATION_DURATION_MS = 5000;
 const CONFETTI_DURATION_MS = 5000;
+const hasConfiguredConfetti = (confetti) => {
+    return confetti === false || (typeof confetti === 'object' && confetti !== null);
+};
+const collectComplexConfetti = (achievements, confettiByAchievementId) => {
+    Object.values(achievements).forEach((metricAchievements) => {
+        metricAchievements.forEach(({ achievementDetails }) => {
+            const confetti = achievementDetails.confetti;
+            if (hasConfiguredConfetti(confetti)) {
+                confettiByAchievementId.set(achievementDetails.achievementId, confetti);
+            }
+        });
+    });
+};
+const simpleConfigHasRewardConfetti = (achievements) => {
+    return Object.values(achievements).some((metricAchievements) => Object.values(metricAchievements).some((achievement) => hasConfiguredConfetti(achievement.confetti)));
+};
+const prepareAchievementsForConfetti = (achievements) => {
+    const confettiByAchievementId = new Map();
+    if (!achievements) {
+        return { achievements, confettiByAchievementId };
+    }
+    if (!isSimpleConfig(achievements)) {
+        collectComplexConfetti(achievements, confettiByAchievementId);
+        return { achievements, confettiByAchievementId };
+    }
+    const simpleAchievements = achievements;
+    if (!simpleConfigHasRewardConfetti(simpleAchievements)) {
+        return { achievements, confettiByAchievementId };
+    }
+    const normalizedAchievements = normalizeAchievements(simpleAchievements);
+    Object.entries(simpleAchievements).forEach(([metric, metricAchievements]) => {
+        const normalizedMetricAchievements = normalizedAchievements[metric] || [];
+        Object.values(metricAchievements).forEach((achievement, index) => {
+            const confetti = achievement.confetti;
+            const normalizedAchievement = normalizedMetricAchievements[index];
+            if (normalizedAchievement && hasConfiguredConfetti(confetti)) {
+                normalizedAchievement.achievementDetails.confetti = confetti;
+                confettiByAchievementId.set(normalizedAchievement.achievementDetails.achievementId, confetti);
+            }
+        });
+    });
+    return { achievements: normalizedAchievements, confettiByAchievementId };
+};
 const AchievementUIContext = createContext({
     icons: {},
     ui: {},
 });
-const AchievementEffects = ({ icons, ui }) => {
-    var _a;
+const AchievementEffects = ({ icons, ui, achievementConfetti }) => {
+    var _a, _b;
     const engine = useAchievementEngine();
     const seenAchievementsRef = useRef(new Set(engine.getUnlocked()));
     const confettiTimerRef = useRef(null);
+    const achievementConfettiRef = useRef(achievementConfetti);
     const [showConfetti, setShowConfetti] = useState(false);
+    const [activeConfettiConfig, setActiveConfettiConfig] = useState(null);
     const [notifications, setNotifications] = useState([]);
     const notificationDuration = (_a = ui.notificationDuration) !== null && _a !== void 0 ? _a : DEFAULT_NOTIFICATION_DURATION_MS;
+    const themeName = ui.theme || 'modern';
+    const themeConfig = useMemo(() => getTheme(themeName) || builtInThemes.modern, [themeName]);
+    const globalConfettiConfig = useMemo(() => (Object.assign(Object.assign({}, themeConfig.confetti), ui.confetti)), [themeConfig, ui.confetti]);
+    const globalConfettiConfigRef = useRef(globalConfettiConfig);
+    const renderedConfettiConfig = showConfetti && activeConfettiConfig ? activeConfettiConfig : globalConfettiConfig;
+    const renderedConfettiDuration = (_b = renderedConfettiConfig.duration) !== null && _b !== void 0 ? _b : CONFETTI_DURATION_MS;
+    useEffect(() => {
+        achievementConfettiRef.current = achievementConfetti;
+    }, [achievementConfetti]);
+    useEffect(() => {
+        globalConfettiConfigRef.current = globalConfettiConfig;
+    }, [globalConfettiConfig]);
+    useEffect(() => {
+        if (ui.enableConfetti === false) {
+            if (confettiTimerRef.current) {
+                clearTimeout(confettiTimerRef.current);
+                confettiTimerRef.current = null;
+            }
+            setShowConfetti(false);
+            setActiveConfettiConfig(null);
+        }
+    }, [ui.enableConfetti]);
     useEffect(() => {
         const unsubscribeUnlocked = engine.on('achievement:unlocked', (event) => {
+            var _a;
             if (seenAchievementsRef.current.has(event.achievementId)) {
                 return;
             }
@@ -578,15 +609,19 @@ const AchievementEffects = ({ icons, ui }) => {
                     return [...currentNotifications, unlockedAchievement];
                 });
             }
-            if (ui.enableConfetti !== false) {
+            const rewardConfetti = achievementConfettiRef.current.get(event.achievementId);
+            if (ui.enableConfetti !== false && rewardConfetti !== false) {
                 if (confettiTimerRef.current) {
                     clearTimeout(confettiTimerRef.current);
                 }
+                const resolvedConfettiConfig = Object.assign(Object.assign({}, globalConfettiConfigRef.current), (rewardConfetti || {}));
+                const resolvedConfettiDuration = (_a = resolvedConfettiConfig.duration) !== null && _a !== void 0 ? _a : CONFETTI_DURATION_MS;
+                setActiveConfettiConfig(resolvedConfettiConfig);
                 setShowConfetti(true);
                 confettiTimerRef.current = setTimeout(() => {
                     setShowConfetti(false);
                     confettiTimerRef.current = null;
-                }, CONFETTI_DURATION_MS);
+                }, resolvedConfettiDuration);
             }
         });
         const unsubscribeStateChanged = engine.on('state:changed', () => {
@@ -610,18 +645,19 @@ const AchievementEffects = ({ icons, ui }) => {
     return (React.createElement(React.Fragment, null,
         ui.enableNotifications !== false &&
             notifications.map((notification, index) => (React.createElement(NotificationComponent, { key: notification.achievementId, achievement: notification, onClose: () => setNotifications((currentNotifications) => currentNotifications.filter((currentNotification) => currentNotification.achievementId !== notification.achievementId)), duration: notificationDuration, position: ui.notificationPosition || 'top-center', theme: ui.theme || 'modern', icons: icons, stackIndex: index }))),
-        ui.enableConfetti !== false && (React.createElement(ConfettiComponentResolved, { show: showConfetti, duration: CONFETTI_DURATION_MS }))));
+        ui.enableConfetti !== false && (React.createElement(ConfettiComponentResolved, Object.assign({ show: showConfetti }, renderedConfettiConfig, { duration: renderedConfettiDuration })))));
 };
 const AchievementProvider = (_a) => {
     var { children, icons = {}, ui = {}, useBuiltInUI } = _a, providerProps = __rest(_a, ["children", "icons", "ui", "useBuiltInUI"]);
     if (useBuiltInUI !== undefined) {
         warnDeprecation('`useBuiltInUI` is deprecated and is now a no-op because built-in UI is the default. It will be removed in 5.0.');
     }
+    const [{ achievements: preparedAchievements, confettiByAchievementId }] = useState(() => prepareAchievementsForConfetti(providerProps.achievements));
     const uiContextValue = useMemo(() => ({ icons, ui }), [icons, ui]);
     return (React.createElement(AchievementUIContext.Provider, { value: uiContextValue },
-        React.createElement(AchievementProvider$1, Object.assign({}, providerProps, { icons: icons }),
+        React.createElement(AchievementProvider$1, Object.assign({}, providerProps, { achievements: preparedAchievements, icons: icons }),
             children,
-            React.createElement(AchievementEffects, { icons: icons, ui: ui }))));
+            React.createElement(AchievementEffects, { achievementConfetti: confettiByAchievementId, icons: icons, ui: ui }))));
 };
 
 const useAchievements = () => {
@@ -1397,5 +1433,45 @@ const BuiltInModal = ({ isOpen, onClose, achievements, icons = {}, theme = 'mode
                 })))))));
 };
 
+/**
+ * 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;
+}
+
 export { AchievementContext, AchievementProvider, AchievementsList, AchievementsModal, AchievementsWidget, BadgesButton, BadgesButtonWithModal, BadgesModal, BuiltInConfetti, BuiltInModal, BuiltInNotification, ConfettiWrapper, AchievementProvider$1 as HeadlessAchievementProvider, LevelProgress, defaultAchievementIcons, defaultStyles, isAsyncStorage, useAchievementEngine, useAchievementState, useAchievements, useSimpleAchievements, useWindowSize };
 //# sourceMappingURL=index.esm.js.map