react-achievements 3.5.0 → 3.6.1

package/dist/index.d.ts

@@ -1,5 +1,135 @@
 import React$1 from 'react';
 
+/**
+ * Notification component interface
+ * Displays achievement unlock notifications
+ */
+interface NotificationProps {
+    achievement: {
+        id: string;
+        title: string;
+        description: string;
+        icon: string;
+    };
+    onClose?: () => void;
+    duration?: number;
+    position?: NotificationPosition;
+    theme?: string;
+}
+type NotificationComponent = React$1.FC<NotificationProps>;
+/**
+ * Modal component interface
+ * Displays list of achievements (locked/unlocked)
+ */
+interface ModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    achievements: AchievementWithStatus[];
+    icons?: Record<string, string>;
+    theme?: string;
+}
+type ModalComponent = React$1.FC<ModalProps>;
+/**
+ * Confetti component interface
+ * Displays celebration animation
+ */
+interface ConfettiProps {
+    show: boolean;
+    duration?: number;
+    particleCount?: number;
+    colors?: string[];
+}
+type ConfettiComponent = React$1.FC<ConfettiProps>;
+/**
+ * Notification positioning options
+ */
+type NotificationPosition = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+/**
+ * Theme configuration interface
+ * Defines styling for all UI components
+ */
+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
+ */
+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;
+}
+
 type AchievementMetricValue = number | string | boolean | Date | null | undefined;
 type AchievementMetricArrayValue = AchievementMetricValue | AchievementMetricValue[];
 interface AchievementMetrics {
@@ -16,12 +146,7 @@ interface AchievementWithStatus extends AchievementDetails {
 }
 interface AchievementCondition {
     isConditionMet: (value: AchievementMetricArrayValue, state: AchievementState) => boolean;
-    achievementDetails: {
-        achievementId: string;
-        achievementTitle: string;
-        achievementDescription: string;
-        achievementIconKey: string;
-    };
+    achievementDetails: AchievementDetails | AchievementWithStatus;
 }
 interface AchievementConfiguration {
     [key: string]: AchievementCondition[];
@@ -326,9 +451,25 @@ declare class OfflineQueueStorage implements AsyncAchievementStorage {
 
 interface BadgesButtonProps {
     onClick: () => void;
-    position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    /**
+     * Position for fixed placement mode
+     * Only used when placement='fixed'
+     */
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    /**
+     * Placement mode
+     * - 'fixed': Traditional floating button with fixed positioning
+     * - 'inline': Regular component that can be placed in drawers, nav bars, etc.
+     * @default 'fixed'
+     */
+    placement?: 'fixed' | 'inline';
     styles?: React$1.CSSProperties;
     unlockedAchievements: AchievementDetails[];
+    /**
+     * Theme name for styling (matches notification/modal theme)
+     * @default 'modern'
+     */
+    theme?: string;
 }
 declare const BadgesButton: React$1.FC<BadgesButtonProps>;
 
@@ -422,6 +563,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;
 }
 declare const AchievementProvider: React$1.FC<AchievementProviderProps>;
 
@@ -673,4 +827,39 @@ declare function exportAchievementData(metrics: AchievementMetrics, unlocked: st
  */
 declare function createConfigHash(config: any): string;
 
-export { AchievementBuilder, AchievementCondition, AchievementConfiguration, AchievementConfigurationType, AchievementContext, AchievementContextValue, AchievementDetails, AchievementError, AchievementMetricArrayValue, AchievementMetricValue, AchievementMetrics, AchievementProvider, AchievementProviderProps$1 as AchievementProviderProps, AchievementState, AchievementStorage, AchievementWithStatus, AnyAchievementStorage, AsyncAchievementStorage, AsyncStorageAdapter, AwardDetails, BadgesButton, BadgesModal, ConfettiWrapper, ConfigurationError, CustomAchievementDetails, ExportedData, ImportOptions, ImportResult, ImportValidationError, IndexedDBStorage, InitialAchievementMetrics, LocalStorage, MemoryStorage, OfflineQueueStorage, RestApiStorage, RestApiStorageConfig, SimpleAchievementConfig, SimpleAchievementDetails, StorageError, StorageQuotaError, StorageType, StylesProps, SyncError, createConfigHash, defaultAchievementIcons, defaultStyles, exportAchievementData, importAchievementData, isAchievementError, isAsyncStorage, isRecoverableError, isSimpleConfig, normalizeAchievements, useAchievements, useSimpleAchievements };
+/**
+ * Built-in notification component
+ * Modern, theme-aware achievement notification with smooth animations
+ */
+declare const BuiltInNotification: React$1.FC<NotificationProps>;
+
+/**
+ * Built-in modal component
+ * Modern, theme-aware achievement modal with smooth animations
+ */
+declare const BuiltInModal: React$1.FC<ModalProps>;
+
+/**
+ * Built-in confetti component
+ * Lightweight CSS-based confetti animation
+ */
+declare const BuiltInConfetti: React$1.FC<ConfettiProps>;
+
+/**
+ * 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}`);
+ * ```
+ */
+declare function useWindowSize(): {
+    width: number;
+    height: number;
+};
+
+export { AchievementBuilder, AchievementCondition, AchievementConfiguration, AchievementConfigurationType, AchievementContext, AchievementContextValue, AchievementDetails, AchievementError, AchievementMetricArrayValue, AchievementMetricValue, AchievementMetrics, AchievementProvider, AchievementProviderProps$1 as AchievementProviderProps, AchievementState, AchievementStorage, AchievementWithStatus, AnyAchievementStorage, AsyncAchievementStorage, AsyncStorageAdapter, AwardDetails, BadgesButton, BadgesModal, BuiltInConfetti, BuiltInModal, BuiltInNotification, ConfettiComponent, ConfettiProps, ConfettiWrapper, ConfigurationError, CustomAchievementDetails, ExportedData, ImportOptions, ImportResult, ImportValidationError, IndexedDBStorage, InitialAchievementMetrics, LocalStorage, MemoryStorage, ModalComponent, ModalProps, NotificationComponent, NotificationPosition, NotificationProps, OfflineQueueStorage, RestApiStorage, RestApiStorageConfig, SimpleAchievementConfig, SimpleAchievementDetails, StorageError, StorageQuotaError, StorageType, StylesProps, SyncError, ThemeConfig, UIConfig, createConfigHash, defaultAchievementIcons, defaultStyles, exportAchievementData, importAchievementData, isAchievementError, isAsyncStorage, isRecoverableError, isSimpleConfig, normalizeAchievements, useAchievements, useSimpleAchievements, useWindowSize };