react-achievements 3.9.3 → 4.1.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import React$1 from 'react';
 import * as achievements_engine from 'achievements-engine';
-import { ImportOptions, ImportResult, AchievementWithStatus as AchievementWithStatus$1, AchievementEngine, AchievementConfigurationType as AchievementConfigurationType$1, AchievementStorage as AchievementStorage$1, AsyncAchievementStorage as AsyncAchievementStorage$1, StorageType, RestApiStorageConfig, EventMapping, AchievementError } from 'achievements-engine';
+import { AchievementWithStatus as AchievementWithStatus$1, ImportOptions, ImportResult, AchievementEngine, AchievementConfigurationType as AchievementConfigurationType$1, AchievementStorage as AchievementStorage$1, AsyncAchievementStorage as AsyncAchievementStorage$1, StorageType, RestApiStorageConfig, EventMapping, AchievementError } from 'achievements-engine';
 export { AchievementBuilder, AchievementEngine, AchievementEngineApi, AchievementError, AchievementUnlockedEvent, AsyncStorageAdapter, AwardDetails, ConfigurationError, EngineConfig, EngineEvent, ErrorEvent, EventMapping, ExportedData, ImportOptions, ImportResult, ImportValidationError, IndexedDBStorage, LocalStorage, MemoryStorage, MetricUpdatedEvent, MetricUpdater, OfflineQueueStorage, RestApiStorage, RestApiStorageConfig, StateChangedEvent, StorageError, StorageQuotaError, StorageType, SyncError, UnsubscribeFn, createConfigHash, exportAchievementData, importAchievementData, isAchievementError, isRecoverableError, isSimpleConfig, normalizeAchievements } from 'achievements-engine';
 
 /**
@@ -14,6 +14,12 @@ interface NotificationProps {
     position?: NotificationPosition;
     theme?: string;
     icons?: Record<string, string>;
+    /**
+     * Position in the active notification stack.
+     * Built-in notifications use this to avoid overlap when multiple
+     * achievements unlock from the same update.
+     */
+    stackIndex?: number;
 }
 type NotificationComponent = React$1.FC<NotificationProps>;
 /**
@@ -84,29 +90,24 @@ interface ThemeConfig {
 interface UIConfig {
     /**
      * Custom notification component
-     * If not provided, uses built-in or legacy component based on detection
+     * If not provided, uses the built-in notification component.
      */
     NotificationComponent?: NotificationComponent;
     /**
-     * Custom modal component
-     * If not provided, uses built-in or legacy component based on detection
+     * Custom modal component used by AchievementsWidget and AchievementsModal.
+     * If not provided, uses the built-in AchievementsModal implementation.
      */
     ModalComponent?: ModalComponent;
     /**
      * Custom confetti component
-     * If not provided, uses built-in or legacy component based on detection
+     * If not provided, uses the built-in confetti component.
      */
     ConfettiComponent?: ConfettiComponent;
     /**
-     * Theme to use (built-in name or registered custom theme name)
+     * Built-in 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'
@@ -122,11 +123,6 @@ interface UIConfig {
      * @default true
      */
     enableConfetti?: boolean;
-    /**
-     * Enable/disable modal
-     * @default true
-     */
-    enableModal?: boolean;
 }
 
 type AchievementMetricValue = number | string | boolean | Date | null | undefined;
@@ -188,7 +184,7 @@ interface AsyncAchievementStorage {
 type AnyAchievementStorage = AchievementStorage | AsyncAchievementStorage;
 declare function isAsyncStorage(storage: AnyAchievementStorage): storage is AsyncAchievementStorage;
 /**
- * @deprecated This type is outdated and will be removed in v4.0.0.
+ * @deprecated This type is outdated and will be removed in 4.2.
  * Use AchievementContextType from 'react-achievements' instead.
  *
  * This legacy interface does not include the 'engine' property.
@@ -222,26 +218,22 @@ interface StylesProps {
         lockIcon?: React.CSSProperties;
         lockedAchievementItem?: React.CSSProperties;
     };
-}
-interface AchievementProviderProps$1 {
-    children: React.ReactNode;
-    config: AchievementConfiguration;
-    initialState?: InitialAchievementMetrics & {
-        previouslyAwardedAchievements?: string[];
+    levelProgress?: {
+        container?: React.CSSProperties;
+        header?: React.CSSProperties;
+        levelLabel?: React.CSSProperties;
+        valueText?: React.CSSProperties;
+        progressTrack?: React.CSSProperties;
+        progressBar?: React.CSSProperties;
+        progressText?: React.CSSProperties;
     };
-    storageKey?: string;
-    badgesButtonPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
-    styles?: Partial<StylesProps>;
-    icons?: Record<string, string>;
-    storage?: AchievementStorage;
-    onAchievementUnlocked?: (achievement: AchievementDetails) => void;
 }
 
 interface AchievementContextType {
     update: (metrics: Record<string, any>) => void;
     achievements: {
         unlocked: string[];
-        all: Record<string, any>;
+        all: Record<string, AchievementWithStatus$1>;
     };
     reset: () => void;
     getState: () => {
@@ -252,6 +244,11 @@ interface AchievementContextType {
     importData: (jsonString: string, options?: ImportOptions) => ImportResult;
     getAllAchievements: () => AchievementWithStatus$1[];
     engine: AchievementEngine;
+    icons: Record<string, string>;
+    /**
+     * @deprecated Use provider props or the presence of an injected engine directly.
+     * This compatibility flag will be removed in 4.2.
+     */
     _isLegacyPattern: boolean;
 }
 declare const AchievementContext: React$1.Context<AchievementContextType | undefined>;
@@ -265,20 +262,80 @@ interface AchievementProviderProps {
     icons?: Record<string, string>;
     onError?: (error: AchievementError) => void;
     /**
-     * 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
+     * @deprecated Built-in UI is the default in the web provider. This prop is a
+     * no-op and will be removed in 4.2.
      */
     useBuiltInUI?: boolean;
 }
-declare const AchievementProvider: React$1.FC<AchievementProviderProps>;
+declare const AchievementProvider$1: React$1.FC<AchievementProviderProps>;
+
+interface AchievementsListRenderItemProps {
+    achievement: AchievementWithStatus;
+    isLocked: boolean;
+    icon: string;
+    index: number;
+}
+interface AchievementsListProps {
+    achievements?: AchievementWithStatus[];
+    showLocked?: boolean;
+    showUnlockConditions?: boolean;
+    icons?: Record<string, string>;
+    styles?: StylesProps['badgesModal'];
+    emptyState?: React$1.ReactNode;
+    className?: string;
+    renderAchievement?: (props: AchievementsListRenderItemProps) => React$1.ReactNode;
+}
+declare const AchievementsList: React$1.FC<AchievementsListProps>;
+
+type AchievementsWidgetPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+type AchievementsWidgetPlacement = 'fixed' | 'inline';
+interface AchievementsWidgetTriggerButtonProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement> {
+    'data-placement': AchievementsWidgetPlacement;
+    'data-testid': string;
+}
+interface AchievementsWidgetTriggerProps {
+    open: () => void;
+    label: string;
+    unlockedCount: number;
+    totalCount: number;
+    unlockedAchievements: AchievementWithStatus[];
+    allAchievements: AchievementWithStatus[];
+    buttonProps: AchievementsWidgetTriggerButtonProps;
+}
+interface AchievementsWidgetProps {
+    position?: AchievementsWidgetPosition;
+    placement?: AchievementsWidgetPlacement;
+    showAllAchievements?: boolean;
+    showUnlockConditions?: boolean;
+    showCount?: boolean;
+    icons?: Record<string, string>;
+    theme?: string;
+    label?: string;
+    icon?: React$1.ReactNode;
+    triggerClassName?: string;
+    renderTrigger?: (props: AchievementsWidgetTriggerProps) => React$1.ReactNode;
+    buttonStyles?: React$1.CSSProperties;
+    modalStyles?: StylesProps['badgesModal'];
+    modalTitle?: React$1.ReactNode;
+    emptyState?: React$1.ReactNode;
+    renderAchievement?: AchievementsListProps['renderAchievement'];
+}
+declare const AchievementsWidget: React$1.FC<AchievementsWidgetProps>;
+
+interface AchievementsModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    achievements?: AchievementWithStatus[];
+    title?: React$1.ReactNode;
+    styles?: StylesProps['badgesModal'];
+    icons?: Record<string, string>;
+    showLocked?: boolean;
+    showUnlockConditions?: boolean;
+    emptyState?: React$1.ReactNode;
+    renderAchievement?: AchievementsListProps['renderAchievement'];
+    theme?: string;
+}
+declare const AchievementsModal: React$1.FC<AchievementsModalProps>;
 
 interface BadgesButtonProps {
     onClick: () => void;
@@ -302,6 +359,10 @@ interface BadgesButtonProps {
      */
     theme?: string;
 }
+/**
+ * @deprecated Use `AchievementsWidget` for new integrations. This v3
+ * compatibility wrapper will be removed in 4.2.
+ */
 declare const BadgesButton: React$1.FC<BadgesButtonProps>;
 
 interface BadgesModalProps {
@@ -314,6 +375,11 @@ interface BadgesModalProps {
     showUnlockConditions?: boolean;
     allAchievements?: AchievementWithStatus[];
 }
+/**
+ * @deprecated Use `AchievementsModal`, `AchievementsWidget`, or
+ * `AchievementsList` for new integrations. This v3 compatibility wrapper will
+ * be removed in 4.2.
+ */
 declare const BadgesModal: React$1.FC<BadgesModalProps>;
 
 interface BadgesButtonWithModalProps {
@@ -329,149 +395,93 @@ interface BadgesButtonWithModalProps {
     modalStyles?: StylesProps['badgesModal'];
 }
 /**
- * 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"
- * />
- * ```
+ * @deprecated Use `AchievementsWidget` for new integrations. This v3
+ * compatibility wrapper will be removed in 4.2.
  */
 declare const BadgesButtonWithModal: React$1.FC<BadgesButtonWithModalProps>;
 
 interface ConfettiWrapperProps {
     show: boolean;
 }
+/**
+ * @deprecated Use the provider `ui.ConfettiComponent` option or the built-in
+ * confetti default. This v3 compatibility wrapper will be removed in 4.2.
+ */
 declare const ConfettiWrapper: React$1.FC<ConfettiWrapperProps>;
 
+interface LevelProgressProps {
+    level: number | string;
+    currentXP: number;
+    nextLevelXP: number;
+    label?: string;
+    valueLabel?: string;
+    showValues?: boolean;
+    showPercent?: boolean;
+    theme?: string;
+    styles?: StylesProps['levelProgress'];
+    className?: string;
+}
+declare const LevelProgress: React$1.FC<LevelProgressProps>;
+
+interface WebAchievementProviderProps extends AchievementProviderProps {
+    icons?: Record<string, string>;
+    ui?: UIConfig;
+    /**
+     * @deprecated Built-in UI is the default in v4. This prop is a no-op and will
+     * be removed in 4.2.
+     */
+    useBuiltInUI?: boolean;
+}
+declare const AchievementProvider: React$1.FC<WebAchievementProviderProps>;
+
 declare const useAchievements: () => AchievementContextType;
 
 /**
  * A simplified hook for achievement tracking.
- * Provides an easier API for common use cases while maintaining access to advanced features.
+ * Provides the v4 happy path for direct metric updates plus explicit state names.
  */
 declare const useSimpleAchievements: () => {
-    /**
-     * Track a metric value for achievements
-     * @param metric - The metric name (e.g., 'score', 'level')
-     * @param value - The metric value
-     */
     track: (metric: string, value: any) => void;
-    /**
-     * 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: string, amount?: number) => void;
-    /**
-     * Track multiple metrics at once
-     * @param metrics - Object with metric names as keys and values
-     */
     trackMultiple: (metrics: Record<string, any>) => void;
-    /**
-     * Array of unlocked achievement IDs
-     */
-    unlocked: string[];
-    /**
-     * All available achievements
-     */
-    all: Record<string, any>;
-    /**
-     * Number of unlocked achievements
-     */
+    unlockedIds: string[];
+    unlockedAchievements: achievements_engine.AchievementWithStatus[];
+    allAchievements: achievements_engine.AchievementWithStatus[];
     unlockedCount: number;
-    /**
-     * Reset all achievement progress
-     */
+    totalCount: number;
+    metrics: Record<string, any>;
     reset: () => void;
-    /**
-     * Get current state (advanced usage)
-     */
     getState: () => {
         metrics: Record<string, any>;
         unlocked: string[];
     };
-    /**
-     * Export achievement data to JSON string
-     * @returns JSON string containing all achievement data
-     */
     exportData: () => string;
+    importData: (jsonString: string, options?: achievements_engine.ImportOptions) => achievements_engine.ImportResult;
+    getAllAchievements: () => achievements_engine.AchievementWithStatus[];
     /**
-     * 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
+     * @deprecated Use `unlockedIds` instead. This alias will be removed in 4.2.
      */
-    importData: (jsonString: string, options?: achievements_engine.ImportOptions) => achievements_engine.ImportResult;
+    unlocked: string[];
     /**
-     * Get all achievements with their unlock status
-     * @returns Array of achievements with isUnlocked boolean property
+     * @deprecated Use `allAchievements` instead. This alias will be removed in 4.2.
      */
-    getAllAchievements: () => achievements_engine.AchievementWithStatus[];
+    all: achievements_engine.AchievementWithStatus[];
+};
+
+declare const useAchievementState: () => {
+    unlockedIds: string[];
+    unlockedAchievements: achievements_engine.AchievementWithStatus[];
+    allAchievements: achievements_engine.AchievementWithStatus[];
+    unlockedCount: number;
+    totalCount: number;
+    metrics: Record<string, any>;
 };
 
 /**
- * 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);
- * }
- * ```
+ * Access the active AchievementEngine instance.
  *
- * @returns AchievementEngine instance
- * @throws Error if used with old achievements prop pattern
- * @throws Error if used outside AchievementProvider
- * @since 3.8.0
+ * In v4 this works with both provider-created engines (`achievements` prop) and
+ * injected engines (`engine` prop).
  */
 declare const useAchievementEngine: () => AchievementEngine;
 
@@ -521,4 +531,4 @@ declare function useWindowSize(): {
     height: number;
 };
 
-export { AchievementCondition, AchievementConfiguration, AchievementConfigurationType, AchievementContext, AchievementContextType, AchievementContextValue, AchievementDetails, AchievementMetricArrayValue, AchievementMetricValue, AchievementMetrics, AchievementProvider, AchievementProviderProps$1 as AchievementProviderProps, AchievementState, AchievementStorage, AchievementWithStatus, AnyAchievementStorage, AsyncAchievementStorage, BadgesButton, BadgesButtonWithModal, BadgesModal, BuiltInConfetti, BuiltInModal, BuiltInNotification, ConfettiComponent, ConfettiProps, ConfettiWrapper, CustomAchievementDetails, InitialAchievementMetrics, ModalComponent, ModalProps, NotificationComponent, NotificationPosition, NotificationProps, SimpleAchievementConfig, SimpleAchievementDetails, StylesProps, ThemeConfig, UIConfig, defaultAchievementIcons, defaultStyles, isAsyncStorage, useAchievementEngine, useAchievements, useSimpleAchievements, useWindowSize };
+export { AchievementCondition, AchievementConfiguration, AchievementConfigurationType, AchievementContext, AchievementContextType, AchievementContextValue, AchievementDetails, AchievementMetricArrayValue, AchievementMetricValue, AchievementMetrics, AchievementProvider, WebAchievementProviderProps as AchievementProviderProps, AchievementState, AchievementStorage, AchievementWithStatus, AchievementsList, AchievementsListProps, AchievementsListRenderItemProps, AchievementsModal, AchievementsModalProps, AchievementsWidget, AchievementsWidgetPlacement, AchievementsWidgetPosition, AchievementsWidgetProps, AchievementsWidgetTriggerButtonProps, AchievementsWidgetTriggerProps, AnyAchievementStorage, AsyncAchievementStorage, BadgesButton, BadgesButtonWithModal, BadgesModal, BuiltInConfetti, BuiltInModal, BuiltInNotification, ConfettiComponent, ConfettiProps, ConfettiWrapper, CustomAchievementDetails, AchievementProvider$1 as HeadlessAchievementProvider, InitialAchievementMetrics, LevelProgress, ModalComponent, ModalProps, NotificationComponent, NotificationPosition, NotificationProps, SimpleAchievementConfig, SimpleAchievementDetails, StylesProps, ThemeConfig, UIConfig, defaultAchievementIcons, defaultStyles, isAsyncStorage, useAchievementEngine, useAchievementState, useAchievements, useSimpleAchievements, useWindowSize };