react-achievements 4.1.0 → 4.2.0

package/dist/index.esm.js

@@ -63,15 +63,12 @@ function warnDeprecation(message) {
 }
 
 const AchievementContext = createContext(undefined);
-const getAllAchievementRecord = (engine) => {
-    return Object.fromEntries(engine.getAllAchievements().map((achievement) => [
-        achievement.achievementId,
-        achievement,
-    ]));
+const getAllAchievementRecord = (achievements) => {
+    return Object.fromEntries(achievements.map((achievement) => [achievement.achievementId, achievement]));
 };
 const AchievementProvider$1 = ({ achievements: achievementsConfig, storage = 'local', children, onError, useBuiltInUI, restApiConfig, engine: externalEngine, eventMapping, icons = {}, }) => {
     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 4.2.');
+        warnDeprecation('`useBuiltInUI` is deprecated and is now a no-op because built-in UI is the default. It will be removed in 5.0.');
     }
     if (achievementsConfig && externalEngine) {
         throw new Error('Cannot provide both "achievements" and "engine" props to AchievementProvider.\n\n' +
@@ -97,15 +94,9 @@ const AchievementProvider$1 = ({ achievements: achievementsConfig, storage = 'lo
             eventMapping,
         });
     });
-    const [achievementState, setAchievementState] = useState(() => ({
-        unlocked: [...engine.getUnlocked()],
-        all: getAllAchievementRecord(engine),
-    }));
-    const syncAchievementState = useCallback(() => {
-        setAchievementState({
-            unlocked: [...engine.getUnlocked()],
-            all: getAllAchievementRecord(engine),
-        });
+    const [achievementSnapshot, setAchievementSnapshot] = useState(() => engine.getSnapshot());
+    const syncAchievementState = useCallback((snapshot) => {
+        setAchievementSnapshot(snapshot || engine.getSnapshot());
     }, [engine]);
     useEffect(() => {
         return () => {
@@ -115,10 +106,17 @@ const AchievementProvider$1 = ({ achievements: achievementsConfig, storage = 'lo
         };
     }, [engine, externalEngine]);
     useEffect(() => {
-        const unsubscribeUnlocked = engine.on('achievement:unlocked', syncAchievementState);
-        const unsubscribeStateChanged = engine.on('state:changed', syncAchievementState);
+        let isMounted = true;
+        const unsubscribeStateChanged = engine.on('state:changed', (event) => {
+            syncAchievementState(event);
+        });
+        engine.ready().then(() => {
+            if (isMounted) {
+                syncAchievementState();
+            }
+        });
         return () => {
-            unsubscribeUnlocked();
+            isMounted = false;
             unsubscribeStateChanged();
         };
     }, [engine, syncAchievementState]);
@@ -127,18 +125,12 @@ const AchievementProvider$1 = ({ achievements: achievementsConfig, storage = 'lo
     };
     const reset = () => {
         engine.reset();
-        syncAchievementState();
     };
     const getState = () => {
-        const metrics = engine.getMetrics();
-        const unlocked = engine.getUnlocked();
-        const metricsInArrayFormat = {};
-        Object.entries(metrics).forEach(([key, value]) => {
-            metricsInArrayFormat[key] = Array.isArray(value) ? value : [value];
-        });
+        const snapshot = engine.getSnapshot();
         return {
-            metrics: metricsInArrayFormat,
-            unlocked: [...unlocked],
+            metrics: snapshot.metrics,
+            unlocked: snapshot.unlockedIds,
         };
     };
     const exportData = () => {
@@ -150,11 +142,16 @@ const AchievementProvider$1 = ({ achievements: achievementsConfig, storage = 'lo
         return result;
     };
     const getAllAchievements = () => {
-        return engine.getAllAchievements();
+        return engine.getSnapshot().allAchievements;
+    };
+    const achievements = {
+        unlocked: achievementSnapshot.unlockedIds,
+        all: getAllAchievementRecord(achievementSnapshot.allAchievements),
     };
     return (React.createElement(AchievementContext.Provider, { value: {
             update,
-            achievements: achievementState,
+            achievements,
+            snapshot: achievementSnapshot,
             reset,
             getState,
             exportData,
@@ -606,7 +603,7 @@ const AchievementEffects = ({ icons, ui }) => {
 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 4.2.');
+        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 uiContextValue = useMemo(() => ({ icons, ui }), [icons, ui]);
     return (React.createElement(AchievementUIContext.Provider, { value: uiContextValue },
@@ -624,18 +621,14 @@ const useAchievements = () => {
 };
 
 const useAchievementState = () => {
-    const { achievements, getAllAchievements, getState } = useAchievements();
-    const allAchievements = getAllAchievements();
-    const unlockedIds = achievements.unlocked;
-    const unlockedAchievementSet = new Set(unlockedIds);
-    const unlockedAchievements = allAchievements.filter((achievement) => unlockedAchievementSet.has(achievement.achievementId));
+    const { snapshot } = useAchievements();
     return {
-        unlockedIds,
-        unlockedAchievements,
-        allAchievements,
-        unlockedCount: unlockedIds.length,
-        totalCount: allAchievements.length,
-        metrics: getState().metrics,
+        unlockedIds: snapshot.unlockedIds,
+        unlockedAchievements: snapshot.unlockedAchievements,
+        allAchievements: snapshot.allAchievements,
+        unlockedCount: snapshot.unlockedCount,
+        totalCount: snapshot.totalCount,
+        metrics: snapshot.metrics,
     };
 };
 
@@ -776,13 +769,98 @@ const defaultStyles = {
     },
 };
 
+const isNumericString = (value) => /^-?\d+(\.\d+)?$/.test(value);
+const getBackdropBlurFilter = (backdropBlur) => {
+    if (backdropBlur === undefined) {
+        return undefined;
+    }
+    if (typeof backdropBlur === 'number') {
+        if (backdropBlur <= 0) {
+            return undefined;
+        }
+        return `blur(${backdropBlur}px)`;
+    }
+    const trimmedBlur = backdropBlur.trim();
+    if (!trimmedBlur ||
+        trimmedBlur === '0' ||
+        trimmedBlur === '0px' ||
+        trimmedBlur === 'none') {
+        return undefined;
+    }
+    const blurValue = isNumericString(trimmedBlur) ? `${trimmedBlur}px` : trimmedBlur;
+    return blurValue.startsWith('blur(') ? blurValue : `blur(${blurValue})`;
+};
+const getBackdropBlurStyles = (backdropBlur) => {
+    const backdropFilter = getBackdropBlurFilter(backdropBlur);
+    if (!backdropFilter) {
+        return {};
+    }
+    return {
+        backdropFilter,
+        WebkitBackdropFilter: backdropFilter,
+    };
+};
+
+const compactAchievementStyles = {
+    achievementList: {
+        display: 'grid',
+        gridTemplateColumns: 'repeat(auto-fill, minmax(120px, 1fr))',
+        gap: '10px',
+    },
+    achievementItem: {
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        justifyContent: 'center',
+        gap: '6px',
+        padding: '12px 10px',
+        borderRadius: '8px',
+        aspectRatio: '1 / 1',
+        minHeight: '120px',
+        textAlign: 'center',
+    },
+    lockedAchievementItem: {
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        justifyContent: 'center',
+        gap: '6px',
+        padding: '12px 10px',
+        borderRadius: '8px',
+        aspectRatio: '1 / 1',
+        minHeight: '120px',
+        textAlign: 'center',
+    },
+    achievementIcon: {
+        fontSize: '34px',
+        lineHeight: 1,
+        flexShrink: 0,
+    },
+    achievementTitle: {
+        margin: '0',
+        fontSize: '13px',
+        lineHeight: 1.2,
+    },
+    achievementDescription: {
+        margin: '0',
+        fontSize: '11px',
+        lineHeight: 1.25,
+    },
+    lockIcon: {
+        fontSize: '15px',
+        top: '8px',
+        right: '8px',
+        transform: 'none',
+    },
+};
+const getDensityStyles = (density) => (density === 'compact' ? compactAchievementStyles : {});
 const resolveIcon = (achievement, icons) => {
     return ((achievement.achievementIconKey && icons[achievement.achievementIconKey]) ||
         achievement.achievementIconKey ||
         icons.default ||
         '⭐');
 };
-const AchievementsList = ({ achievements, showLocked = true, showUnlockConditions = false, icons = {}, styles = {}, emptyState, className, renderAchievement, }) => {
+const AchievementsList = ({ achievements, showLocked = true, showUnlockConditions = false, icons = {}, styles = {}, emptyState, className, density = 'comfortable', renderAchievement, }) => {
     const context = useContext(AchievementContext);
     const uiContext = useContext(AchievementUIContext);
     const mergedIcons = Object.assign(Object.assign(Object.assign(Object.assign({}, defaultAchievementIcons), context === null || context === void 0 ? void 0 : context.icons), uiContext.icons), icons);
@@ -793,36 +871,37 @@ const AchievementsList = ({ achievements, showLocked = true, showUnlockCondition
     const achievementsToDisplay = showLocked
         ? sourceAchievements
         : sourceAchievements.filter((achievement) => achievement.isUnlocked);
+    const densityStyles = getDensityStyles(density);
     if (achievementsToDisplay.length === 0) {
         return (React.createElement("p", { style: { textAlign: 'center', color: '#666' } }, emptyState || 'No achievements configured.'));
     }
-    return (React.createElement("div", { className: className, style: Object.assign(Object.assign({}, defaultStyles.badgesModal.achievementList), styles === null || styles === void 0 ? void 0 : styles.achievementList), "data-testid": "achievements-list" }, achievementsToDisplay.map((achievement, index) => {
+    return (React.createElement("div", { className: className, style: Object.assign(Object.assign(Object.assign({}, defaultStyles.badgesModal.achievementList), densityStyles === null || densityStyles === void 0 ? void 0 : densityStyles.achievementList), styles === null || styles === void 0 ? void 0 : styles.achievementList), "data-density": density, "data-testid": "achievements-list" }, achievementsToDisplay.map((achievement, index) => {
         const isLocked = !achievement.isUnlocked;
         const icon = resolveIcon(achievement, mergedIcons);
         if (renderAchievement) {
-            return (React.createElement(React.Fragment, { key: achievement.achievementId }, renderAchievement({ achievement, isLocked, icon, index })));
+            return (React.createElement(React.Fragment, { key: achievement.achievementId }, renderAchievement({ achievement, isLocked, icon, index, density })));
         }
         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' }), "data-testid": "achievement-list-item", "data-unlocked": achievement.isUnlocked ? 'true' : 'false' },
-            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 }) }, icon),
-            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),
-                achievement.achievementDescription && (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' }) },
+                ? Object.assign(Object.assign(Object.assign({}, defaultStyles.badgesModal.lockedAchievementItem), densityStyles === null || densityStyles === void 0 ? void 0 : densityStyles.lockedAchievementItem), styles === null || styles === void 0 ? void 0 : styles.lockedAchievementItem) : Object.assign(Object.assign({}, defaultStyles.badgesModal.achievementItem), densityStyles === null || densityStyles === void 0 ? void 0 : densityStyles.achievementItem))), styles === null || styles === void 0 ? void 0 : styles.achievementItem), { position: 'relative' }), "data-testid": "achievement-list-item", "data-unlocked": achievement.isUnlocked ? 'true' : 'false' },
+            React.createElement("div", { style: Object.assign(Object.assign(Object.assign(Object.assign({}, defaultStyles.badgesModal.achievementIcon), densityStyles === null || densityStyles === void 0 ? void 0 : densityStyles.achievementIcon), styles === null || styles === void 0 ? void 0 : styles.achievementIcon), { opacity: isLocked ? 0.4 : 1 }) }, icon),
+            React.createElement("div", { style: density === 'compact' ? { width: '100%', minWidth: 0 } : { flex: 1 } },
+                React.createElement("h3", { style: Object.assign(Object.assign(Object.assign(Object.assign({}, defaultStyles.badgesModal.achievementTitle), densityStyles === null || densityStyles === void 0 ? void 0 : densityStyles.achievementTitle), styles === null || styles === void 0 ? void 0 : styles.achievementTitle), { color: isLocked ? '#999' : undefined }) }, achievement.achievementTitle),
+                achievement.achievementDescription && (React.createElement("p", { style: Object.assign(Object.assign(Object.assign(Object.assign({}, defaultStyles.badgesModal.achievementDescription), densityStyles === null || densityStyles === void 0 ? void 0 : densityStyles.achievementDescription), styles === null || styles === void 0 ? void 0 : styles.achievementDescription), { color: isLocked ? '#aaa' : '#666' }) },
                     achievement.achievementDescription,
                     showUnlockConditions && isLocked && (React.createElement("span", { style: {
                             display: 'block',
-                            fontSize: '12px',
-                            marginTop: '4px',
+                            fontSize: density === 'compact' ? '11px' : '12px',
+                            marginTop: density === 'compact' ? '2px' : '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"))));
+            isLocked && (React.createElement("div", { style: Object.assign(Object.assign(Object.assign({}, defaultStyles.badgesModal.lockIcon), densityStyles === null || densityStyles === void 0 ? void 0 : densityStyles.lockIcon), styles === null || styles === void 0 ? void 0 : styles.lockIcon) }, "\uD83D\uDD12"))));
     })));
 };
 
-const AchievementsModal = ({ isOpen, onClose, achievements, title = '🏆 Achievements', styles = {}, icons = {}, showLocked = true, showUnlockConditions = false, emptyState, renderAchievement, theme, }) => {
+const AchievementsModal = ({ isOpen, onClose, achievements, title = '🏆 Achievements', styles = {}, icons = {}, showLocked = true, showUnlockConditions = false, emptyState, renderAchievement, theme, hideScrollbar = false, density = 'comfortable', backdropBlur, }) => {
     const context = useContext(AchievementContext);
     const uiContext = useContext(AchievementUIContext);
     useEffect(() => {
@@ -850,19 +929,30 @@ const AchievementsModal = ({ isOpen, onClose, achievements, title = '🏆 Achiev
         ? sourceAchievements
         : sourceAchievements === null || sourceAchievements === void 0 ? void 0 : sourceAchievements.filter((achievement) => achievement.isUnlocked);
     const resolvedTheme = theme || uiContext.ui.theme || 'modern';
+    const backdropBlurFilter = getBackdropBlurFilter(backdropBlur);
     const mergedIcons = Object.assign(Object.assign(Object.assign(Object.assign({}, defaultAchievementIcons), context === null || context === void 0 ? void 0 : context.icons), uiContext.icons), icons);
     if (CustomModal) {
         if (!modalAchievements) {
             throw new Error('AchievementsModal requires either an achievements prop or an AchievementProvider parent.');
         }
-        return (React.createElement(CustomModal, { isOpen: isOpen, onClose: onClose, achievements: modalAchievements, icons: mergedIcons, theme: resolvedTheme }));
+        return (React.createElement(CustomModal, { isOpen: isOpen, onClose: onClose, achievements: modalAchievements, icons: mergedIcons, theme: resolvedTheme, hideScrollbar: hideScrollbar, density: density, backdropBlur: backdropBlur }));
     }
-    return (React.createElement("div", { style: Object.assign(Object.assign({}, defaultStyles.badgesModal.overlay), styles === null || styles === void 0 ? void 0 : styles.overlay), role: "presentation", onClick: onClose, "data-testid": "achievements-modal-overlay" },
-        React.createElement("div", { style: Object.assign(Object.assign({}, defaultStyles.badgesModal.content), styles === null || styles === void 0 ? void 0 : styles.content), role: "dialog", "aria-modal": "true", "aria-labelledby": "achievements-modal-title", onClick: (event) => event.stopPropagation(), "data-testid": "achievements-modal" },
+    return (React.createElement("div", { style: Object.assign(Object.assign(Object.assign({}, defaultStyles.badgesModal.overlay), styles === null || styles === void 0 ? void 0 : styles.overlay), getBackdropBlurStyles(backdropBlur)), role: "presentation", onClick: onClose, "data-backdrop-blur": backdropBlurFilter, "data-testid": "achievements-modal-overlay" },
+        hideScrollbar && (React.createElement("style", null, `
+            [data-react-achievements-modal-content][data-hide-scrollbar="true"] {
+              scrollbar-width: none;
+              -ms-overflow-style: none;
+            }
+
+            [data-react-achievements-modal-content][data-hide-scrollbar="true"]::-webkit-scrollbar {
+              display: none;
+            }
+          `)),
+        React.createElement("div", { style: Object.assign(Object.assign({}, defaultStyles.badgesModal.content), styles === null || styles === void 0 ? void 0 : styles.content), role: "dialog", "aria-modal": "true", "aria-labelledby": "achievements-modal-title", onClick: (event) => event.stopPropagation(), "data-hide-scrollbar": hideScrollbar ? 'true' : undefined, "data-density": density, "data-react-achievements-modal-content": true, "data-testid": "achievements-modal" },
             React.createElement("div", { style: Object.assign(Object.assign({}, defaultStyles.badgesModal.header), styles === null || styles === void 0 ? void 0 : styles.header) },
                 React.createElement("h2", { id: "achievements-modal-title", style: { margin: 0 } }, title),
                 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(AchievementsList, { achievements: modalAchievements, showLocked: showLocked, showUnlockConditions: showUnlockConditions, icons: icons, styles: styles, emptyState: emptyState, renderAchievement: renderAchievement }))));
+            React.createElement(AchievementsList, { achievements: modalAchievements, showLocked: showLocked, showUnlockConditions: showUnlockConditions, icons: icons, styles: styles, emptyState: emptyState, renderAchievement: renderAchievement, density: density }))));
 };
 
 const getPositionStyles$1 = (position) => {
@@ -882,7 +972,7 @@ const getPositionStyles$1 = (position) => {
             return Object.assign(Object.assign({}, base), { bottom: 0, right: 0 });
     }
 };
-const AchievementsWidget = ({ position = 'bottom-right', placement = 'fixed', showAllAchievements = true, showUnlockConditions = false, showCount = true, icons, theme, label = 'Achievements', icon = '🏆', triggerClassName, renderTrigger, buttonStyles, modalStyles, modalTitle, emptyState, renderAchievement, }) => {
+const AchievementsWidget = ({ position = 'bottom-right', placement = 'fixed', showAllAchievements = true, showUnlockConditions = false, showCount = true, icons, theme, density = 'comfortable', label = 'Achievements', icon = '🏆', triggerClassName, renderTrigger, buttonStyles, modalStyles, modalTitle, emptyState, renderAchievement, hideModalScrollbar = false, modalBackdropBlur, }) => {
     const uiContext = useContext(AchievementUIContext);
     const [isModalOpen, setIsModalOpen] = useState(false);
     const { unlockedAchievements, allAchievements, unlockedCount, totalCount } = useAchievementState();
@@ -922,7 +1012,7 @@ const AchievementsWidget = ({ position = 'bottom-right', placement = 'fixed', sh
             React.createElement("span", null, icon),
             React.createElement("span", { style: { flex: 1 } }, label),
             showCount && React.createElement("span", null, unlockedCount))),
-        React.createElement(AchievementsModal, { isOpen: isModalOpen, onClose: () => setIsModalOpen(false), achievements: modalAchievements, showUnlockConditions: showUnlockConditions, icons: icons, styles: modalStyles, title: modalTitle, emptyState: emptyState, renderAchievement: renderAchievement, theme: resolvedTheme })));
+        React.createElement(AchievementsModal, { isOpen: isModalOpen, onClose: () => setIsModalOpen(false), achievements: modalAchievements, showUnlockConditions: showUnlockConditions, icons: icons, styles: modalStyles, title: modalTitle, emptyState: emptyState, renderAchievement: renderAchievement, theme: resolvedTheme, hideScrollbar: hideModalScrollbar, density: density, backdropBlur: modalBackdropBlur })));
 };
 
 const getPositionStyles = (position) => {
@@ -944,11 +1034,11 @@ const getPositionStyles = (position) => {
 };
 /**
  * @deprecated Use `AchievementsWidget` for new integrations. This v3
- * compatibility wrapper will be removed in 4.2.
+ * compatibility wrapper will be removed in 5.0.
  */
 const BadgesButton = ({ onClick, position = 'bottom-right', placement = 'fixed', styles = {}, unlockedAchievements, theme = 'modern', }) => {
     React.useEffect(() => {
-        warnDeprecation('`BadgesButton` is deprecated. Use `AchievementsWidget` instead. `BadgesButton` will be removed in 4.2.');
+        warnDeprecation('`BadgesButton` is deprecated. Use `AchievementsWidget` instead. `BadgesButton` will be removed in 5.0.');
     }, []);
     // Get theme configuration for consistent styling
     const themeConfig = getTheme(theme) || builtInThemes.modern;
@@ -985,11 +1075,11 @@ const BadgesButton = ({ onClick, position = 'bottom-right', placement = 'fixed',
 /**
  * @deprecated Use `AchievementsModal`, `AchievementsWidget`, or
  * `AchievementsList` for new integrations. This v3 compatibility wrapper will
- * be removed in 4.2.
+ * be removed in 5.0.
  */
 const BadgesModal = ({ isOpen, onClose, achievements, styles = {}, icons = {}, showAllAchievements = false, showUnlockConditions = false, allAchievements, }) => {
     useEffect(() => {
-        warnDeprecation('`BadgesModal` is deprecated. Use `AchievementsWidget` or `AchievementsList` instead. `BadgesModal` will be removed in 4.2.');
+        warnDeprecation('`BadgesModal` is deprecated. Use `AchievementsWidget` or `AchievementsList` instead. `BadgesModal` will be removed in 5.0.');
     }, []);
     const achievementsToDisplay = showAllAchievements && allAchievements
         ? allAchievements
@@ -999,7 +1089,7 @@ const BadgesModal = ({ isOpen, onClose, achievements, styles = {}, icons = {}, s
 
 /**
  * @deprecated Use `AchievementsWidget` for new integrations. This v3
- * compatibility wrapper will be removed in 4.2.
+ * compatibility wrapper will be removed in 5.0.
  */
 const BadgesButtonWithModal = ({ unlockedAchievements, position = 'bottom-right', placement = 'fixed', showAllAchievements = false, allAchievements, showUnlockConditions = false, icons, theme = 'modern', buttonStyles, modalStyles, }) => {
     const [isModalOpen, setIsModalOpen] = useState(false);
@@ -1010,11 +1100,11 @@ const BadgesButtonWithModal = ({ unlockedAchievements, position = 'bottom-right'
 
 /**
  * @deprecated Use the provider `ui.ConfettiComponent` option or the built-in
- * confetti default. This v3 compatibility wrapper will be removed in 4.2.
+ * confetti default. This v3 compatibility wrapper will be removed in 5.0.
  */
 const ConfettiWrapper = ({ show }) => {
     useEffect(() => {
-        warnDeprecation('`ConfettiWrapper` is deprecated. Use the provider `ui.ConfettiComponent` option or built-in confetti defaults instead. `ConfettiWrapper` will be removed in 4.2.');
+        warnDeprecation('`ConfettiWrapper` is deprecated. Use the provider `ui.ConfettiComponent` option or built-in confetti defaults instead. `ConfettiWrapper` will be removed in 5.0.');
     }, []);
     return React.createElement(BuiltInConfetti, { show: show, particleCount: 200 });
 };
@@ -1049,17 +1139,11 @@ const LevelProgress = ({ level, currentXP, nextLevelXP, label = 'Level', valueLa
  * Provides the v4 happy path for direct metric updates plus explicit state names.
  */
 const useSimpleAchievements = () => {
-    const { update, reset, getState, exportData, importData } = useAchievements();
+    const { update, reset, getState, exportData, importData, engine } = useAchievements();
     const achievementState = useAchievementState();
     const track = (metric, value) => update({ [metric]: value });
     const 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 });
+        return engine.increment(metric, amount);
     };
     const trackMultiple = (metrics) => update(metrics);
     return {
@@ -1078,11 +1162,11 @@ const useSimpleAchievements = () => {
         importData,
         getAllAchievements: () => achievementState.allAchievements,
         /**
-         * @deprecated Use `unlockedIds` instead. This alias will be removed in 4.2.
+         * @deprecated Use `unlockedIds` instead. This alias will be removed in 5.0.
          */
         unlocked: achievementState.unlockedIds,
         /**
-         * @deprecated Use `allAchievements` instead. This alias will be removed in 4.2.
+         * @deprecated Use `allAchievements` instead. This alias will be removed in 5.0.
          */
         all: achievementState.allAchievements,
     };
@@ -1092,12 +1176,14 @@ const useSimpleAchievements = () => {
  * Built-in modal component
  * Modern, theme-aware achievement modal with smooth animations
  */
-const BuiltInModal = ({ isOpen, onClose, achievements, icons = {}, theme = 'modern', }) => {
+const BuiltInModal = ({ isOpen, onClose, achievements, icons = {}, theme = 'modern', hideScrollbar = false, density = 'comfortable', backdropBlur, }) => {
     // 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;
+    const isCompact = density === 'compact';
+    const backdropBlurFilter = getBackdropBlurFilter(backdropBlur);
     useEffect(() => {
         if (isOpen) {
             // Lock body scroll when modal is open
@@ -1113,24 +1199,12 @@ const BuiltInModal = ({ isOpen, onClose, achievements, icons = {}, theme = 'mode
     }, [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 overlayStyles = Object.assign({ 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' }, getBackdropBlurStyles(backdropBlur));
     const modalStyles = {
         background: themeStyles.background,
         borderRadius: themeStyles.borderRadius,
-        padding: '32px',
-        maxWidth: '600px',
+        padding: isCompact ? '18px' : '32px',
+        maxWidth: isCompact ? '520px' : '600px',
         width: '90%',
         maxHeight: '80vh',
         overflow: 'auto',
@@ -1142,18 +1216,18 @@ const BuiltInModal = ({ isOpen, onClose, achievements, icons = {}, theme = 'mode
         display: 'flex',
         justifyContent: 'space-between',
         alignItems: 'center',
-        marginBottom: '24px',
+        marginBottom: isCompact ? '16px' : '24px',
     };
     const titleStyles = {
         margin: 0,
         color: themeStyles.textColor,
-        fontSize: themeStyles.headerFontSize || '28px',
+        fontSize: isCompact ? '22px' : themeStyles.headerFontSize || '28px',
         fontWeight: 'bold',
     };
     const closeButtonStyles = {
         background: 'none',
         border: 'none',
-        fontSize: '32px',
+        fontSize: isCompact ? '26px' : '32px',
         cursor: 'pointer',
         color: themeStyles.textColor,
         opacity: 0.6,
@@ -1161,17 +1235,17 @@ const BuiltInModal = ({ isOpen, onClose, achievements, icons = {}, theme = 'mode
         padding: 0,
         lineHeight: 1,
     };
-    const isBadgeLayout = themeStyles.achievementLayout === 'badge';
+    const isBadgeLayout = isCompact || themeStyles.achievementLayout === 'badge';
     const listStyles = isBadgeLayout
         ? {
             display: 'grid',
-            gridTemplateColumns: 'repeat(auto-fill, minmax(140px, 1fr))',
-            gap: '16px',
+            gridTemplateColumns: `repeat(auto-fill, minmax(${isCompact ? '112px' : '140px'}, 1fr))`,
+            gap: isCompact ? '10px' : '16px',
         }
         : {
             display: 'flex',
             flexDirection: 'column',
-            gap: '12px',
+            gap: isCompact ? '8px' : '12px',
         };
     const getAchievementItemStyles = (isUnlocked) => {
         const baseStyles = {
@@ -1185,24 +1259,24 @@ const BuiltInModal = ({ isOpen, onClose, achievements, icons = {}, theme = 'mode
         };
         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' });
+            return Object.assign(Object.assign({}, baseStyles), { display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center', textAlign: 'center', padding: isCompact ? '12px 8px' : '20px 12px', aspectRatio: '1 / 1.1', minHeight: isCompact ? '118px' : '160px' });
         }
         else {
             // Horizontal layout (default)
-            return Object.assign(Object.assign({}, baseStyles), { display: 'flex', gap: '16px', padding: '16px' });
+            return Object.assign(Object.assign({}, baseStyles), { display: 'flex', gap: isCompact ? '10px' : '16px', padding: isCompact ? '10px 12px' : '16px' });
         }
     };
     const getIconContainerStyles = (isUnlocked) => {
         if (isBadgeLayout) {
             return {
-                fontSize: '48px',
+                fontSize: isCompact ? '32px' : '48px',
                 lineHeight: 1,
-                marginBottom: '8px',
+                marginBottom: isCompact ? '6px' : '8px',
                 opacity: isUnlocked ? 1 : 0.3,
             };
         }
         return {
-            fontSize: '40px',
+            fontSize: isCompact ? '28px' : '40px',
             flexShrink: 0,
             lineHeight: 1,
             opacity: isUnlocked ? 1 : 0.3,
@@ -1220,14 +1294,14 @@ const BuiltInModal = ({ isOpen, onClose, achievements, icons = {}, theme = 'mode
         ? {
             margin: '0 0 4px 0',
             color: themeStyles.textColor,
-            fontSize: '14px',
+            fontSize: isCompact ? '12px' : '14px',
             fontWeight: 'bold',
             lineHeight: '1.3',
         }
         : {
-            margin: '0 0 8px 0',
+            margin: isCompact ? '0 0 4px 0' : '0 0 8px 0',
             color: themeStyles.textColor,
-            fontSize: '18px',
+            fontSize: isCompact ? '14px' : '18px',
             fontWeight: 'bold',
             overflow: 'hidden',
             textOverflow: 'ellipsis',
@@ -1238,27 +1312,27 @@ const BuiltInModal = ({ isOpen, onClose, achievements, icons = {}, theme = 'mode
             margin: 0,
             color: themeStyles.textColor,
             opacity: 0.7,
-            fontSize: '11px',
+            fontSize: isCompact ? '10px' : '11px',
             lineHeight: '1.3',
         }
         : {
             margin: 0,
             color: themeStyles.textColor,
             opacity: 0.8,
-            fontSize: '14px',
+            fontSize: isCompact ? '12px' : '14px',
         };
     const getLockIconStyles = () => {
         if (isBadgeLayout) {
             return {
                 position: 'absolute',
-                top: '8px',
-                right: '8px',
-                fontSize: '18px',
+                top: isCompact ? '6px' : '8px',
+                right: isCompact ? '6px' : '8px',
+                fontSize: isCompact ? '14px' : '18px',
                 opacity: 0.6,
             };
         }
         return {
-            fontSize: '24px',
+            fontSize: isCompact ? '18px' : '24px',
             flexShrink: 0,
             opacity: 0.5,
         };
@@ -1279,9 +1353,18 @@ const BuiltInModal = ({ isOpen, onClose, achievements, icons = {}, theme = 'mode
               opacity: 1;
             }
           }
+
+          [data-react-achievements-built-in-modal][data-hide-scrollbar="true"] {
+            scrollbar-width: none;
+            -ms-overflow-style: none;
+          }
+
+          [data-react-achievements-built-in-modal][data-hide-scrollbar="true"]::-webkit-scrollbar {
+            display: none;
+          }
         `),
-        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: overlayStyles, onClick: onClose, "data-backdrop-blur": backdropBlurFilter, "data-testid": "built-in-modal-overlay" },
+            React.createElement("div", { style: modalStyles, onClick: (e) => e.stopPropagation(), "data-hide-scrollbar": hideScrollbar ? 'true' : undefined, "data-density": density, "data-react-achievements-built-in-modal": true, "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")),