react-achievements 3.9.1 → 4.0.0

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

@@ -1,115 +0,0 @@
-export type AchievementMetricValue = number | string | boolean | Date | null | undefined;
-export type AchievementMetricArrayValue = AchievementMetricValue | AchievementMetricValue[];
-export declare const isDate: (value: any) => value is Date;
-export interface AchievementMetrics {
-    [key: string]: AchievementMetricValue[];
-}
-export interface AchievementDetails {
-    achievementId: string;
-    achievementTitle: string;
-    achievementDescription: string;
-    achievementIconKey?: string;
-}
-export interface AchievementWithStatus extends AchievementDetails {
-    isUnlocked: boolean;
-}
-export interface AchievementCondition {
-    isConditionMet: (value: AchievementMetricArrayValue, state: AchievementState) => boolean;
-    achievementDetails: AchievementDetails | AchievementWithStatus;
-}
-export interface AchievementConfiguration {
-    [key: string]: AchievementCondition[];
-}
-export interface SimpleAchievementDetails {
-    title: string;
-    description?: string;
-    icon?: string;
-}
-export interface CustomAchievementDetails extends SimpleAchievementDetails {
-    condition: (metrics: Record<string, any>) => boolean;
-}
-export interface SimpleAchievementConfig {
-    [metric: string]: {
-        [threshold: string]: SimpleAchievementDetails | CustomAchievementDetails;
-    };
-}
-export type AchievementConfigurationType = AchievementConfiguration | SimpleAchievementConfig;
-export interface InitialAchievementMetrics {
-    [key: string]: AchievementMetricValue;
-}
-export interface AchievementState {
-    metrics: AchievementMetrics;
-    unlockedAchievements: string[];
-}
-export interface AchievementStorage {
-    getMetrics(): AchievementMetrics;
-    setMetrics(metrics: AchievementMetrics): void;
-    getUnlockedAchievements(): string[];
-    setUnlockedAchievements(achievements: string[]): void;
-    clear(): void;
-}
-export interface AsyncAchievementStorage {
-    getMetrics(): Promise<AchievementMetrics>;
-    setMetrics(metrics: AchievementMetrics): Promise<void>;
-    getUnlockedAchievements(): Promise<string[]>;
-    setUnlockedAchievements(achievements: string[]): Promise<void>;
-    clear(): Promise<void>;
-}
-export type AnyAchievementStorage = AchievementStorage | AsyncAchievementStorage;
-export declare function isAsyncStorage(storage: AnyAchievementStorage): storage is AsyncAchievementStorage;
-/**
- * @deprecated This type is outdated and will be removed in v4.0.0.
- * Use AchievementContextType from 'react-achievements' instead.
- *
- * This legacy interface does not include the 'engine' property.
- *
- * @example
- * ```typescript
- * // Old (deprecated)
- * import { AchievementContextValue } from 'react-achievements';
- *
- * // New (recommended)
- * import { AchievementContextType } from 'react-achievements';
- * ```
- */
-export interface AchievementContextValue {
-    updateMetrics: (metrics: AchievementMetrics | ((prev: AchievementMetrics) => AchievementMetrics)) => void;
-    unlockedAchievements: string[];
-    resetStorage: () => void;
-}
-export interface StylesProps {
-    badgesButton?: React.CSSProperties;
-    badgesModal?: {
-        overlay?: React.CSSProperties;
-        content?: React.CSSProperties;
-        header?: React.CSSProperties;
-        closeButton?: React.CSSProperties;
-        achievementList?: React.CSSProperties;
-        achievementItem?: React.CSSProperties;
-        achievementTitle?: React.CSSProperties;
-        achievementDescription?: React.CSSProperties;
-        achievementIcon?: React.CSSProperties;
-        lockIcon?: React.CSSProperties;
-        lockedAchievementItem?: React.CSSProperties;
-    };
-}
-export interface AchievementProviderProps {
-    children: React.ReactNode;
-    config: AchievementConfiguration;
-    initialState?: InitialAchievementMetrics & {
-        previouslyAwardedAchievements?: string[];
-    };
-    storageKey?: string;
-    badgesButtonPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
-    styles?: Partial<StylesProps>;
-    icons?: Record<string, string>;
-    storage?: AchievementStorage;
-    onAchievementUnlocked?: (achievement: AchievementDetails) => void;
-}
-export declare enum StorageType {
-    Local = "local",// Synchronous localStorage
-    Memory = "memory",// Synchronous in-memory storage
-    IndexedDB = "indexeddb",// Asynchronous IndexedDB storage
-    RestAPI = "restapi"
-}
-export type { NotificationProps, NotificationComponent, ModalProps, ModalComponent, ConfettiProps, ConfettiComponent, NotificationPosition, ThemeConfig, UIConfig, } from './ui/interfaces';

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

@@ -1,7 +0,0 @@
-import React from 'react';
-import { ConfettiProps } from './interfaces';
-/**
- * Built-in confetti component
- * Lightweight CSS-based confetti animation
- */
-export declare const BuiltInConfetti: React.FC<ConfettiProps>;

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

@@ -1,7 +0,0 @@
-import React from 'react';
-import { ModalProps } from './interfaces';
-/**
- * Built-in modal component
- * Modern, theme-aware achievement modal with smooth animations
- */
-export declare const BuiltInModal: React.FC<ModalProps>;

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

@@ -1,7 +0,0 @@
-import React from 'react';
-import { NotificationProps } from './interfaces';
-/**
- * Built-in notification component
- * Modern, theme-aware achievement notification with smooth animations
- */
-export declare const BuiltInNotification: React.FC<NotificationProps>;

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

@@ -1,21 +0,0 @@
-/**
- * Legacy library wrappers for backwards compatibility
- * Wraps external UI libraries to match our component interfaces
- */
-import type { NotificationComponent, ModalComponent, ConfettiComponent } from './interfaces';
-import { LegacyLibraries } from './legacyDetector';
-/**
- * Wrapper for react-toastify toast notifications
- * Falls back to built-in notification if not available
- */
-export declare const createLegacyToastNotification: (libraries: LegacyLibraries) => NotificationComponent;
-/**
- * Wrapper for react-modal Modal component
- * Falls back to built-in modal if not available
- */
-export declare const createLegacyModalWrapper: (libraries: LegacyLibraries) => ModalComponent;
-/**
- * Wrapper for react-confetti Confetti component
- * Falls back to built-in confetti if not available
- */
-export declare const createLegacyConfettiWrapper: (libraries: LegacyLibraries) => ConfettiComponent;

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

@@ -1,127 +0,0 @@
-import React from 'react';
-import { AchievementWithStatus } from '../types';
-/**
- * Notification component interface
- * Displays achievement unlock notifications
- */
-export interface NotificationProps {
-    achievement: AchievementWithStatus;
-    onClose?: () => void;
-    duration?: number;
-    position?: NotificationPosition;
-    theme?: string;
-    icons?: Record<string, 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

@@ -1,40 +0,0 @@
-/**
- * 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

@@ -1,14 +0,0 @@
-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/core/utils/configNormalizer.d.ts

@@ -1,3 +0,0 @@
-import { AchievementConfiguration, SimpleAchievementConfig, AchievementConfigurationType } from '../types';
-export declare function isSimpleConfig(config: AchievementConfigurationType): config is SimpleAchievementConfig;
-export declare function normalizeAchievements(config: AchievementConfigurationType): AchievementConfiguration;

package/dist/types/core/utils/dataExport.d.ts

@@ -1,34 +0,0 @@
-import { AchievementMetrics } from '../types';
-/**
- * Structure of exported achievement data
- */
-export interface ExportedData {
-    version: string;
-    timestamp: number;
-    metrics: AchievementMetrics;
-    unlockedAchievements: string[];
-    configHash?: string;
-}
-/**
- * Exports achievement data to a JSON string
- *
- * @param metrics - Current achievement metrics
- * @param unlocked - Array of unlocked achievement IDs
- * @param configHash - Optional hash of achievement configuration for validation
- * @returns JSON string containing all achievement data
- *
- * @example
- * ```typescript
- * const json = exportAchievementData(_metrics, ['score_100', 'level_5']);
- * // Save json to file or send to server
- * ```
- */
-export declare function exportAchievementData(metrics: AchievementMetrics, unlocked: string[], configHash?: string): string;
-/**
- * Creates a simple hash of the achievement configuration
- * Used to validate that imported data matches the current configuration
- *
- * @param config - Achievement configuration object
- * @returns Simple hash string
- */
-export declare function createConfigHash(config: any): string;

package/dist/types/core/utils/dataImport.d.ts

@@ -1,50 +0,0 @@
-import { AchievementMetrics } from '../types';
-/**
- * Options for importing achievement data
- */
-export interface ImportOptions {
-    /** Strategy for merging imported data with existing data */
-    mergeStrategy?: 'replace' | 'merge' | 'preserve';
-    /** Whether to validate the imported data */
-    validate?: boolean;
-    /** Optional config hash to validate against */
-    expectedConfigHash?: string;
-}
-/**
- * Result of an import operation
- */
-export interface ImportResult {
-    success: boolean;
-    imported: {
-        metrics: number;
-        achievements: number;
-    };
-    errors?: string[];
-    warnings?: string[];
-}
-/**
- * Imports achievement data from a JSON string
- *
- * @param jsonString - JSON string containing exported achievement data
- * @param currentMetrics - Current metrics state
- * @param currentUnlocked - Current unlocked achievements
- * @param options - Import options
- * @returns Import result with success status and any errors
- *
- * @example
- * ```typescript
- * const result = importAchievementData(
- *   jsonString,
- *   currentMetrics,
- *   currentUnlocked,
- *   { mergeStrategy: 'merge', validate: true }
- * );
- *
- * if (result.success) {
- *   console.log(`Imported ${result.imported.achievements} achievements`);
- * } else {
- *   console.error('Import failed:', result.errors);
- * }
- * ```
- */
-export declare function importAchievementData(jsonString: string, currentMetrics: AchievementMetrics, currentUnlocked: string[], options?: ImportOptions): ImportResult;

package/dist/types/hooks/useAchievementEngine.d.ts

@@ -1,36 +0,0 @@
-import type { AchievementEngine } from 'achievements-engine';
-/**
- * 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);
- * }
- * ```
- *
- * @returns AchievementEngine instance
- * @throws Error if used with old achievements prop pattern
- * @throws Error if used outside AchievementProvider
- * @since 3.8.0
- */
-export declare const useAchievementEngine: () => AchievementEngine;

package/dist/types/hooks/useAchievements.d.ts

@@ -1 +0,0 @@
-export declare const useAchievements: () => import("../providers/AchievementProvider").AchievementContextType;

package/dist/types/hooks/useSimpleAchievements.d.ts

@@ -1,63 +0,0 @@
-/**
- * A simplified hook for achievement tracking.
- * Provides an easier API for common use cases while maintaining access to advanced features.
- */
-export 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
-     */
-    unlockedCount: number;
-    /**
-     * Reset all achievement progress
-     */
-    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;
-    /**
-     * 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
-     */
-    importData: (jsonString: string, options?: import("achievements-engine").ImportOptions) => import("achievements-engine").ImportResult;
-    /**
-     * Get all achievements with their unlock status
-     * @returns Array of achievements with isUnlocked boolean property
-     */
-    getAllAchievements: () => import("achievements-engine").AchievementWithStatus[];
-};

package/dist/types/index.d.ts

@@ -1,36 +0,0 @@
-export type { AchievementMetrics, AchievementConfiguration, AchievementConfigurationType, SimpleAchievementConfig, SimpleAchievementDetails, CustomAchievementDetails, AchievementDetails, AchievementWithStatus, AchievementCondition, AchievementMetricValue, AchievementMetricArrayValue, InitialAchievementMetrics, AchievementState, AchievementStorage, AsyncAchievementStorage, AnyAchievementStorage, AchievementContextValue, // @deprecated - use AchievementContextType instead
-StylesProps, AchievementProviderProps, } from './core/types';
-export type { AchievementContextType, } from './providers/AchievementProvider';
-export { isAsyncStorage } from './core/types';
-export { LocalStorage, MemoryStorage, IndexedDBStorage, RestApiStorage, AsyncStorageAdapter, OfflineQueueStorage, StorageType } from 'achievements-engine';
-export type { RestApiStorageConfig } from 'achievements-engine';
-export { BadgesButton } from './core/components/BadgesButton';
-export { BadgesModal } from './core/components/BadgesModal';
-export { BadgesButtonWithModal } from './core/components/BadgesButtonWithModal';
-export { ConfettiWrapper } from './core/components/ConfettiWrapper';
-export { AchievementProvider, AchievementContext } from './providers/AchievementProvider';
-export { useAchievements } from './hooks/useAchievements';
-export { useSimpleAchievements } from './hooks/useSimpleAchievements';
-export { useAchievementEngine } from './hooks/useAchievementEngine';
-export { defaultStyles } from './core/styles/defaultStyles';
-export { defaultAchievementIcons } from './core/icons/defaultIcons';
-export { normalizeAchievements, isSimpleConfig, exportAchievementData, createConfigHash, importAchievementData } from 'achievements-engine';
-export type { ImportOptions, ImportResult, ExportedData } from 'achievements-engine';
-/**
- * Achievement Builder Utilities
- *
- * These utilities are re-exported from achievements-engine for backwards compatibility.
- * They provide a convenient builder API for creating achievement configurations.
- *
- * @see https://github.com/dave-b-b/achievements-engine for full documentation
- */
-export { AchievementBuilder, type AwardDetails, } from 'achievements-engine';
-export { AchievementError, StorageQuotaError, ImportValidationError, StorageError, ConfigurationError, SyncError, isAchievementError, isRecoverableError } from 'achievements-engine';
-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';
-export { AchievementEngine } from 'achievements-engine';
-export type { AchievementEngineApi } from 'achievements-engine';
-export type { EngineConfig, EngineEvent, AchievementUnlockedEvent, MetricUpdatedEvent, StateChangedEvent, ErrorEvent, EventMapping, MetricUpdater, UnsubscribeFn, } from 'achievements-engine';

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

@@ -1,47 +0,0 @@
-import React from 'react';
-import { AchievementEngine, AchievementError } from 'achievements-engine';
-import type { AchievementConfigurationType, AchievementStorage, AsyncAchievementStorage, StorageType, AchievementWithStatus, EventMapping, ImportOptions, ImportResult, RestApiStorageConfig } from 'achievements-engine';
-import { UIConfig } from '../core/types';
-export interface AchievementContextType {
-    update: (metrics: Record<string, any>) => void;
-    achievements: {
-        unlocked: string[];
-        all: Record<string, any>;
-    };
-    reset: () => void;
-    getState: () => {
-        metrics: Record<string, any>;
-        unlocked: string[];
-    };
-    exportData: () => string;
-    importData: (jsonString: string, options?: ImportOptions) => ImportResult;
-    getAllAchievements: () => AchievementWithStatus[];
-    engine: AchievementEngine;
-    _isLegacyPattern: boolean;
-}
-export declare const AchievementContext: React.Context<AchievementContextType | undefined>;
-interface AchievementProviderProps {
-    achievements?: AchievementConfigurationType;
-    storage?: AchievementStorage | AsyncAchievementStorage | StorageType;
-    restApiConfig?: RestApiStorageConfig;
-    eventMapping?: EventMapping;
-    engine?: AchievementEngine;
-    children: React.ReactNode;
-    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
-     */
-    useBuiltInUI?: boolean;
-}
-export declare const AchievementProvider: React.FC<AchievementProviderProps>;
-export {};

package/dist/types/setupTests.d.ts

@@ -1 +0,0 @@
-import '@testing-library/jest-dom';