react-achievements 3.5.0 → 3.6.1

package/dist/types/core/ui/interfaces.d.ts

@@ -0,0 +1,131 @@
+import React from 'react';
+import { AchievementWithStatus } from '../types';
+/**
+ * Notification component interface
+ * Displays achievement unlock notifications
+ */
+export interface NotificationProps {
+    achievement: {
+        id: string;
+        title: string;
+        description: string;
+        icon: string;
+    };
+    onClose?: () => void;
+    duration?: number;
+    position?: NotificationPosition;
+    theme?: string;
+}
+export type NotificationComponent = React.FC<NotificationProps>;
+/**
+ * Modal component interface
+ * Displays list of achievements (locked/unlocked)
+ */
+export interface ModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    achievements: AchievementWithStatus[];
+    icons?: Record<string, string>;
+    theme?: string;
+}
+export type ModalComponent = React.FC<ModalProps>;
+/**
+ * Confetti component interface
+ * Displays celebration animation
+ */
+export interface ConfettiProps {
+    show: boolean;
+    duration?: number;
+    particleCount?: number;
+    colors?: string[];
+}
+export type ConfettiComponent = React.FC<ConfettiProps>;
+/**
+ * Notification positioning options
+ */
+export type NotificationPosition = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+/**
+ * Theme configuration interface
+ * Defines styling for all UI components
+ */
+export interface ThemeConfig {
+    name: string;
+    notification: {
+        background: string;
+        textColor: string;
+        accentColor: string;
+        borderRadius: string;
+        boxShadow: string;
+        fontSize?: {
+            header?: string;
+            title?: string;
+            description?: string;
+        };
+    };
+    modal: {
+        overlayColor: string;
+        background: string;
+        textColor: string;
+        accentColor: string;
+        borderRadius: string;
+        headerFontSize?: string;
+        achievementCardBorderRadius?: string;
+        achievementLayout?: 'horizontal' | 'badge';
+    };
+    confetti: {
+        colors: string[];
+        particleCount: number;
+        shapes?: ('circle' | 'square')[];
+    };
+}
+/**
+ * UI Configuration for AchievementProvider
+ * Allows customization of all UI components
+ */
+export interface UIConfig {
+    /**
+     * Custom notification component
+     * If not provided, uses built-in or legacy component based on detection
+     */
+    NotificationComponent?: NotificationComponent;
+    /**
+     * Custom modal component
+     * If not provided, uses built-in or legacy component based on detection
+     */
+    ModalComponent?: ModalComponent;
+    /**
+     * Custom confetti component
+     * If not provided, uses built-in or legacy component based on detection
+     */
+    ConfettiComponent?: ConfettiComponent;
+    /**
+     * Theme to use (built-in name or registered custom theme name)
+     * Built-in themes: 'modern' (default), 'minimal', 'gamified'
+     */
+    theme?: string;
+    /**
+     * Direct theme configuration override
+     * Takes precedence over theme name
+     */
+    customTheme?: ThemeConfig;
+    /**
+     * Notification positioning
+     * @default 'top-center'
+     */
+    notificationPosition?: NotificationPosition;
+    /**
+     * Enable/disable notifications
+     * @default true
+     */
+    enableNotifications?: boolean;
+    /**
+     * Enable/disable confetti animations
+     * @default true
+     */
+    enableConfetti?: boolean;
+    /**
+     * Enable/disable modal
+     * @default true
+     */
+    enableModal?: boolean;
+}

package/dist/types/core/ui/legacyDetector.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Legacy UI library detection system
+ * Attempts to dynamically import external UI libraries
+ * Shows deprecation warnings when detected
+ */
+export interface LegacyLibraries {
+    toast?: any;
+    ToastContainer?: any;
+    Modal?: any;
+    Confetti?: any;
+    useWindowSize?: any;
+}
+/**
+ * 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
+ */
+export declare function detectLegacyLibraries(): Promise<LegacyLibraries>;
+/**
+ * Synchronous check if libraries are already loaded
+ * Does not trigger detection if not already attempted
+ *
+ * @returns Boolean indicating if legacy libraries were detected
+ */
+export declare function hasLegacyLibraries(): boolean;
+/**
+ * Get cached legacy libraries without re-detection
+ * Returns null if detection hasn't been attempted yet
+ *
+ * @returns Cached LegacyLibraries or null
+ */
+export declare function getCachedLegacyLibraries(): LegacyLibraries | null;
+/**
+ * Reset detection state (useful for testing)
+ *
+ * @internal
+ */
+export declare function resetDetection(): void;

package/dist/types/core/ui/themes.d.ts

@@ -0,0 +1,14 @@
+import { ThemeConfig } from './interfaces';
+/**
+ * Built-in theme presets
+ */
+export declare const builtInThemes: Record<string, ThemeConfig>;
+/**
+ * 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
+ */
+export declare function getTheme(name: string): ThemeConfig | undefined;

package/dist/types/index.d.ts

@@ -20,3 +20,8 @@ export { AchievementBuilder, type AwardDetails, } from './utils/achievementHelpe
 export { AchievementError, StorageQuotaError, ImportValidationError, StorageError, ConfigurationError, SyncError, isAchievementError, isRecoverableError } from './core/errors/AchievementErrors';
 export { exportAchievementData, createConfigHash, type ExportedData } from './core/utils/dataExport';
 export { importAchievementData, type ImportOptions, type ImportResult } from './core/utils/dataImport';
+export { BuiltInNotification } from './core/ui/BuiltInNotification';
+export { BuiltInModal } from './core/ui/BuiltInModal';
+export { BuiltInConfetti } from './core/ui/BuiltInConfetti';
+export type { NotificationComponent, NotificationProps, ModalComponent, ModalProps, ConfettiComponent, ConfettiProps, NotificationPosition, ThemeConfig, UIConfig, } from './core/types';
+export { useWindowSize } from './core/hooks/useWindowSize';

package/dist/types/providers/AchievementProvider.d.ts

@@ -1,7 +1,6 @@
 import React from 'react';
-import { AchievementConfigurationType, AchievementStorage, AsyncAchievementStorage, AchievementMetrics, StorageType, AchievementWithStatus } from '../core/types';
+import { AchievementConfigurationType, AchievementStorage, AsyncAchievementStorage, AchievementMetrics, StorageType, AchievementWithStatus, UIConfig } from '../core/types';
 import { RestApiStorageConfig } from '../core/storage/RestApiStorage';
-import 'react-toastify/dist/ReactToastify.css';
 import { ImportOptions, ImportResult } from '../core/utils/dataImport';
 import { AchievementError } from '../core/errors/AchievementErrors';
 export interface AchievementContextType {
@@ -27,6 +26,19 @@ interface AchievementProviderProps {
     icons?: Record<string, string>;
     onError?: (error: AchievementError) => void;
     restApiConfig?: RestApiStorageConfig;
+    /**
+     * UI configuration for notifications, modal, and confetti
+     * NEW in v3.6.0
+     */
+    ui?: UIConfig;
+    /**
+     * Force use of built-in UI components (opt-in for v3.x)
+     * Set to true to skip legacy library detection and use built-in UI
+     * In v4.0.0, this will become the default behavior
+     * NEW in v3.6.0
+     * @default false
+     */
+    useBuiltInUI?: boolean;
 }
 export declare const AchievementProvider: React.FC<AchievementProviderProps>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-achievements",
-  "version": "3.5.0",
+  "version": "3.6.1",
   "description": "Core achievement system for React applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,6 +27,20 @@
     "react-toastify": "^9.1.3",
     "react-use": "^17.4.0"
   },
+  "peerDependenciesMeta": {
+    "react-confetti": {
+      "optional": true
+    },
+    "react-modal": {
+      "optional": true
+    },
+    "react-toastify": {
+      "optional": true
+    },
+    "react-use": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@babel/core": "^7.22.5",
     "@babel/preset-env": "^7.22.5",

package/dist/assets/defaultIcons.d.ts

@@ -1,81 +0,0 @@
-export declare const defaultAchievementIcons: {
-    levelUp: string;
-    questComplete: string;
-    monsterDefeated: string;
-    itemCollected: string;
-    challengeCompleted: string;
-    milestoneReached: string;
-    firstStep: string;
-    newBeginnings: string;
-    breakthrough: string;
-    growth: string;
-    shared: string;
-    liked: string;
-    commented: string;
-    followed: string;
-    invited: string;
-    communityMember: string;
-    supporter: string;
-    connected: string;
-    participant: string;
-    influencer: string;
-    activeDay: string;
-    activeWeek: string;
-    activeMonth: string;
-    earlyBird: string;
-    nightOwl: string;
-    streak: string;
-    dedicated: string;
-    punctual: string;
-    consistent: string;
-    marathon: string;
-    artist: string;
-    writer: string;
-    innovator: string;
-    creator: string;
-    expert: string;
-    master: string;
-    pioneer: string;
-    performer: string;
-    thinker: string;
-    explorer: string;
-    bronze: string;
-    silver: string;
-    gold: string;
-    diamond: string;
-    legendary: string;
-    epic: string;
-    rare: string;
-    common: string;
-    special: string;
-    hidden: string;
-    one: string;
-    ten: string;
-    hundred: string;
-    thousand: string;
-    clicked: string;
-    used: string;
-    found: string;
-    built: string;
-    solved: string;
-    discovered: string;
-    unlocked: string;
-    upgraded: string;
-    repaired: string;
-    defended: string;
-    default: string;
-    loading: string;
-    error: string;
-    success: string;
-    failure: string;
-    trophy: string;
-    star: string;
-    flag: string;
-    puzzle: string;
-    gem: string;
-    crown: string;
-    medal: string;
-    ribbon: string;
-    badge: string;
-    shield: string;
-};

package/dist/badges.d.ts

@@ -1,8 +0,0 @@
-export interface BadgeConfig {
-    id: string;
-    icon: string;
-    title: string;
-    description: string;
-}
-declare const defaultBadges: BadgeConfig[];
-export { defaultBadges };

package/dist/components/Achievement.d.ts

@@ -1,10 +0,0 @@
-import React from 'react';
-interface AchievementProps {
-    metric: number;
-    threshold: number;
-    onAchieve: () => void;
-    message: string;
-    children: React.ReactNode;
-}
-declare const _default: React.NamedExoticComponent<AchievementProps>;
-export default _default;

package/dist/components/AchievementModal.d.ts

@@ -1,12 +0,0 @@
-import React from 'react';
-import { AchievementDetails } from '../types';
-import { Styles } from '../defaultStyles';
-interface AchievementModalProps {
-    isOpen: boolean;
-    achievement: AchievementDetails | null;
-    onClose: () => void;
-    styles: Styles['achievementModal'];
-    icons?: Record<string, string>;
-}
-declare const _default: React.NamedExoticComponent<AchievementModalProps>;
-export default _default;

package/dist/components/Badge.d.ts

@@ -1,9 +0,0 @@
-import React from 'react';
-interface BadgeProps {
-    icon: string;
-    title: string;
-    description: string;
-    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
-}
-declare const Badge: React.FC<BadgeProps>;
-export default Badge;

package/dist/components/BadgesButton.d.ts

@@ -1,14 +0,0 @@
-import React from 'react';
-import { Styles } from '../defaultStyles';
-import { AchievementDetails } from '../types';
-interface BadgesButtonProps {
-    onClick: () => void;
-    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
-    styles: Styles['badgesButton'];
-    unlockedAchievements: AchievementDetails[];
-    icon?: React.ReactNode;
-    drawer?: boolean;
-    customStyles?: React.CSSProperties;
-}
-declare const _default: React.NamedExoticComponent<BadgesButtonProps>;
-export default _default;

package/dist/components/BadgesModal.d.ts

@@ -1,12 +0,0 @@
-import React from 'react';
-import { AchievementDetails } from '../types';
-import { Styles } from '../defaultStyles';
-interface BadgesModalProps {
-    isOpen: boolean;
-    achievements: AchievementDetails[];
-    onClose: () => void;
-    styles: Styles['badgesModal'];
-    icons?: Record<string, string>;
-}
-declare const _default: React.NamedExoticComponent<BadgesModalProps>;
-export default _default;

package/dist/components/ConfettiWrapper.d.ts

@@ -1,6 +0,0 @@
-import React from 'react';
-interface ConfettiWrapperProps {
-    show: boolean;
-}
-declare const ConfettiWrapper: React.FC<ConfettiWrapperProps>;
-export default ConfettiWrapper;

package/dist/components/Progress.d.ts

@@ -1,6 +0,0 @@
-import React from 'react';
-interface ProgressProps {
-    style?: React.CSSProperties;
-}
-declare const _default: React.NamedExoticComponent<ProgressProps>;
-export default _default;

package/dist/context/AchievementContext.d.ts

@@ -1,21 +0,0 @@
-import React, { ReactNode } from 'react';
-import { Metrics, AchievementConfig, MetricValue } from '../types';
-import { Styles } from '../defaultStyles';
-interface AchievementContextProps {
-    metrics: Metrics;
-    setMetrics: (metrics: Metrics | ((prevMetrics: Metrics) => Metrics)) => void;
-    unlockedAchievements: string[];
-    checkAchievements: () => void;
-    showBadgesModal: () => void;
-}
-interface AchievementProviderProps {
-    children: ReactNode;
-    config: AchievementConfig;
-    initialState?: Record<string, MetricValue>;
-    storageKey?: string;
-    badgesButtonPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
-    styles?: Partial<Styles>;
-}
-export declare const AchievementProvider: React.FC<AchievementProviderProps>;
-export declare const useAchievement: () => AchievementContextProps;
-export {};

package/dist/defaultStyles.d.ts

@@ -1,19 +0,0 @@
-type StyleObject = {
-    [key: string]: string | number;
-};
-interface BadgesModalStyles {
-    overlay: StyleObject;
-    content: StyleObject;
-    title: StyleObject;
-    badgeContainer: StyleObject;
-    badge: StyleObject;
-    badgeIcon: StyleObject;
-    badgeTitle: StyleObject;
-    button: StyleObject;
-}
-export interface Styles {
-    badgesModal: BadgesModalStyles;
-    badgesButton: StyleObject;
-}
-export declare const defaultStyles: Styles;
-export {};

package/dist/hooks/useAchievement.d.ts

@@ -1,8 +0,0 @@
-export declare const useAchievement: () => {
-    metrics: import("..").AchievementMetrics;
-    unlockedAchievements: string[];
-    notifications: import("..").AchievementDetails[];
-    config: import("../types").SerializedAchievementConfiguration;
-    updateMetrics: (newMetrics: import("..").AchievementMetrics | ((prevMetrics: import("..").AchievementMetrics) => import("..").AchievementMetrics)) => void;
-    resetStorage: () => void;
-};

package/dist/hooks/useAchievementState.d.ts

@@ -1,4 +0,0 @@
-export declare const useAchievementState: () => {
-    metrics: import("..").AchievementMetrics;
-    previouslyAwardedAchievements: string[];
-};