react-achievements 3.9.1 → 4.0.0

package/dist/web.d.ts

@@ -0,0 +1,534 @@
+import React$1 from 'react';
+import * as achievements_engine 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';
+
+/**
+ * Notification component interface
+ * Displays achievement unlock notifications
+ */
+interface NotificationProps {
+    achievement: AchievementWithStatus;
+    onClose?: () => void;
+    duration?: number;
+    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>;
+/**
+ * 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 the built-in notification component.
+     */
+    NotificationComponent?: NotificationComponent;
+    /**
+     * 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 the built-in confetti component.
+     */
+    ConfettiComponent?: ConfettiComponent;
+    /**
+     * Built-in theme name.
+     * Built-in themes: 'modern' (default), 'minimal', 'gamified'
+     */
+    theme?: string;
+    /**
+     * Notification positioning
+     * @default 'top-center'
+     */
+    notificationPosition?: NotificationPosition;
+    /**
+     * Enable/disable notifications
+     * @default true
+     */
+    enableNotifications?: boolean;
+    /**
+     * Enable/disable confetti animations
+     * @default true
+     */
+    enableConfetti?: boolean;
+}
+
+type AchievementMetricValue = number | string | boolean | Date | null | undefined;
+type AchievementMetricArrayValue = AchievementMetricValue | AchievementMetricValue[];
+interface AchievementMetrics {
+    [key: string]: AchievementMetricValue[];
+}
+interface AchievementDetails {
+    achievementId: string;
+    achievementTitle: string;
+    achievementDescription: string;
+    achievementIconKey?: string;
+}
+interface AchievementWithStatus extends AchievementDetails {
+    isUnlocked: boolean;
+}
+interface AchievementCondition {
+    isConditionMet: (value: AchievementMetricArrayValue, state: AchievementState) => boolean;
+    achievementDetails: AchievementDetails | AchievementWithStatus;
+}
+interface AchievementConfiguration {
+    [key: string]: AchievementCondition[];
+}
+interface SimpleAchievementDetails {
+    title: string;
+    description?: string;
+    icon?: string;
+}
+interface CustomAchievementDetails extends SimpleAchievementDetails {
+    condition: (metrics: Record<string, any>) => boolean;
+}
+interface SimpleAchievementConfig {
+    [metric: string]: {
+        [threshold: string]: SimpleAchievementDetails | CustomAchievementDetails;
+    };
+}
+type AchievementConfigurationType = AchievementConfiguration | SimpleAchievementConfig;
+interface InitialAchievementMetrics {
+    [key: string]: AchievementMetricValue;
+}
+interface AchievementState {
+    metrics: AchievementMetrics;
+    unlockedAchievements: string[];
+}
+interface AchievementStorage {
+    getMetrics(): AchievementMetrics;
+    setMetrics(metrics: AchievementMetrics): void;
+    getUnlockedAchievements(): string[];
+    setUnlockedAchievements(achievements: string[]): void;
+    clear(): void;
+}
+interface AsyncAchievementStorage {
+    getMetrics(): Promise<AchievementMetrics>;
+    setMetrics(metrics: AchievementMetrics): Promise<void>;
+    getUnlockedAchievements(): Promise<string[]>;
+    setUnlockedAchievements(achievements: string[]): Promise<void>;
+    clear(): Promise<void>;
+}
+type AnyAchievementStorage = AchievementStorage | AsyncAchievementStorage;
+declare function isAsyncStorage(storage: AnyAchievementStorage): storage is AsyncAchievementStorage;
+/**
+ * @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.
+ *
+ * @example
+ * ```typescript
+ * // Old (deprecated)
+ * import { AchievementContextValue } from 'react-achievements';
+ *
+ * // New (recommended)
+ * import { AchievementContextType } from 'react-achievements';
+ * ```
+ */
+interface AchievementContextValue {
+    updateMetrics: (metrics: AchievementMetrics | ((prev: AchievementMetrics) => AchievementMetrics)) => void;
+    unlockedAchievements: string[];
+    resetStorage: () => void;
+}
+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;
+    };
+    levelProgress?: {
+        container?: React.CSSProperties;
+        header?: React.CSSProperties;
+        levelLabel?: React.CSSProperties;
+        valueText?: React.CSSProperties;
+        progressTrack?: React.CSSProperties;
+        progressBar?: React.CSSProperties;
+        progressText?: React.CSSProperties;
+    };
+}
+
+interface AchievementContextType {
+    update: (metrics: Record<string, any>) => void;
+    achievements: {
+        unlocked: string[];
+        all: Record<string, AchievementWithStatus$1>;
+    };
+    reset: () => void;
+    getState: () => {
+        metrics: Record<string, any>;
+        unlocked: string[];
+    };
+    exportData: () => string;
+    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>;
+interface AchievementProviderProps {
+    achievements?: AchievementConfigurationType$1;
+    storage?: AchievementStorage$1 | AsyncAchievementStorage$1 | StorageType;
+    restApiConfig?: RestApiStorageConfig;
+    eventMapping?: EventMapping;
+    engine?: AchievementEngine;
+    children: React$1.ReactNode;
+    icons?: Record<string, string>;
+    onError?: (error: AchievementError) => void;
+    /**
+     * @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$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;
+    /**
+     * 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;
+}
+/**
+ * @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 {
+    isOpen: boolean;
+    onClose: () => void;
+    achievements: AchievementDetails[];
+    styles?: StylesProps['badgesModal'];
+    icons?: Record<string, string>;
+    showAllAchievements?: boolean;
+    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 {
+    unlockedAchievements: AchievementDetails[];
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    placement?: 'fixed' | 'inline';
+    showAllAchievements?: boolean;
+    allAchievements?: AchievementWithStatus[];
+    showUnlockConditions?: boolean;
+    icons?: Record<string, string>;
+    theme?: string;
+    buttonStyles?: React$1.CSSProperties;
+    modalStyles?: StylesProps['badgesModal'];
+}
+/**
+ * @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 the v4 happy path for direct metric updates plus explicit state names.
+ */
+declare const useSimpleAchievements: () => {
+    track: (metric: string, value: any) => void;
+    increment: (metric: string, amount?: number) => void;
+    trackMultiple: (metrics: Record<string, any>) => void;
+    unlockedIds: string[];
+    unlockedAchievements: achievements_engine.AchievementWithStatus[];
+    allAchievements: achievements_engine.AchievementWithStatus[];
+    unlockedCount: number;
+    totalCount: number;
+    metrics: Record<string, any>;
+    reset: () => void;
+    getState: () => {
+        metrics: Record<string, any>;
+        unlocked: string[];
+    };
+    exportData: () => string;
+    importData: (jsonString: string, options?: achievements_engine.ImportOptions) => achievements_engine.ImportResult;
+    getAllAchievements: () => achievements_engine.AchievementWithStatus[];
+    /**
+     * @deprecated Use `unlockedIds` instead. This alias will be removed in 4.2.
+     */
+    unlocked: string[];
+    /**
+     * @deprecated Use `allAchievements` instead. This alias will be removed in 4.2.
+     */
+    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>;
+};
+
+/**
+ * Access the active AchievementEngine instance.
+ *
+ * In v4 this works with both provider-created engines (`achievements` prop) and
+ * injected engines (`engine` prop).
+ */
+declare const useAchievementEngine: () => AchievementEngine;
+
+declare const defaultStyles: Required<StylesProps>;
+
+declare const defaultAchievementIcons: {
+    default: string;
+    loading: string;
+    error: string;
+    success: string;
+    trophy: string;
+    star: string;
+};
+
+/**
+ * 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 { 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 };