questro/dist/badges/index.d.mts

A lightweight, modular gamification library for React with unique visual components. Features combo meters, daily challenges, achievement toasts, and progress rings. Add points, badges, quests, leaderboards, levels/XP, streaks, and notifications with zero

import { b as Entity, a as EntityId, T as Timestamp, E as EventEmitter, S as StorageAdapter } from '../types-B4P_iNGe.mjs';
import * as react_jsx_runtime from 'react/jsx-runtime';
import { ReactNode, HTMLAttributes } from 'react';

type BadgeRarity = 'common' | 'uncommon' | 'rare' | 'epic' | 'legendary';
type BadgeCategory = string;
interface BadgeCondition {
    type: string;
    value: number;
    metadata?: Record<string, unknown>;
}
interface Badge extends Entity {
    name: string;
    description: string;
    icon?: string;
    image?: string;
    rarity: BadgeRarity;
    category?: BadgeCategory;
    conditions: BadgeCondition[];
    points?: number;
    hidden?: boolean;
}
interface UnlockedBadge extends Entity {
    userId: EntityId;
    badgeId: EntityId;
    unlockedAt: Timestamp;
    progress?: number;
}
interface BadgeProgress {
    badgeId: EntityId;
    current: number;
    target: number;
    percentage: number;
    completed: boolean;
}
interface BadgesConfig {
    userId: EntityId;
    badges: Badge[];
    onBadgeUnlocked?: (badge: Badge) => void;
}
interface BadgesState {
    userId: EntityId;
    unlockedBadges: UnlockedBadge[];
    progress: Record<EntityId, BadgeProgress>;
}
type BadgesEvents = {
    badgeUnlocked: {
        badge: Badge;
        unlockedBadge: UnlockedBadge;
    };
    progressUpdated: {
        badgeId: EntityId;
        progress: BadgeProgress;
    };
    [key: string]: unknown;
};
interface BadgesService {
    getAllBadges(): readonly Badge[];
    getUnlockedBadges(): readonly UnlockedBadge[];
    getLockedBadges(): readonly Badge[];
    getBadgeById(id: EntityId): Badge | undefined;
    isBadgeUnlocked(badgeId: EntityId): boolean;
    getProgress(badgeId: EntityId): BadgeProgress | undefined;
    unlockBadge(badgeId: EntityId): UnlockedBadge | null;
    updateProgress(badgeId: EntityId, value: number): BadgeProgress;
    checkAndUnlockBadges(): UnlockedBadge[];
    reset(): void;
    events: EventEmitter<BadgesEvents>;
}

declare class BadgesServiceImpl implements BadgesService {
    private state;
    private config;
    private badges;
    readonly events: EventEmitter<BadgesEvents>;
    constructor(config: BadgesConfig);
    private initializeProgress;
    private calculateTarget;
    getAllBadges(): readonly Badge[];
    getUnlockedBadges(): readonly UnlockedBadge[];
    getLockedBadges(): readonly Badge[];
    getBadgeById(id: EntityId): Badge | undefined;
    isBadgeUnlocked(badgeId: EntityId): boolean;
    getProgress(badgeId: EntityId): BadgeProgress | undefined;
    unlockBadge(badgeId: EntityId): UnlockedBadge | null;
    updateProgress(badgeId: EntityId, value: number): BadgeProgress;
    checkAndUnlockBadges(): UnlockedBadge[];
    reset(): void;
    toJSON(): BadgesState;
    static fromJSON(config: BadgesConfig, state: BadgesState): BadgesServiceImpl;
}

interface BadgesProviderProps {
    children: ReactNode;
    config: BadgesConfig;
    storage?: StorageAdapter<BadgesState>;
    storageKey?: string;
}
declare function BadgesProvider({ children, config, storage, storageKey, }: BadgesProviderProps): react_jsx_runtime.JSX.Element | null;
declare function useBadgesContext(): BadgesService;

interface UseBadgesReturn {
    allBadges: readonly Badge[];
    unlockedBadges: readonly UnlockedBadge[];
    lockedBadges: readonly Badge[];
    unlockBadge: (badgeId: EntityId) => UnlockedBadge | null;
    updateProgress: (badgeId: EntityId, value: number) => BadgeProgress;
    isBadgeUnlocked: (badgeId: EntityId) => boolean;
    getProgress: (badgeId: EntityId) => BadgeProgress | undefined;
    checkAndUnlockBadges: () => UnlockedBadge[];
    reset: () => void;
}
declare function useBadges(): UseBadgesReturn;

interface BadgeCardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
    badge: Badge;
    children?: (badge: Badge, isUnlocked: boolean, progress?: BadgeProgress) => ReactNode;
}
declare function BadgeCard({ badge, children, ...props }: BadgeCardProps): react_jsx_runtime.JSX.Element;
interface BadgeGridProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
    badges?: readonly Badge[];
    showLocked?: boolean;
    showHidden?: boolean;
    children?: (badge: Badge) => ReactNode;
}
declare function BadgeGrid({ badges: providedBadges, showLocked, showHidden, children, ...props }: BadgeGridProps): react_jsx_runtime.JSX.Element;
interface BadgeProgressBarProps extends HTMLAttributes<HTMLDivElement> {
    badgeId: EntityId;
    showLabel?: boolean;
}
declare function BadgeProgressBar({ badgeId, showLabel, ...props }: BadgeProgressBarProps): react_jsx_runtime.JSX.Element | null;
interface BadgeCountProps extends HTMLAttributes<HTMLSpanElement> {
    type?: 'unlocked' | 'total' | 'locked';
}
declare function BadgeCount({ type, ...props }: BadgeCountProps): react_jsx_runtime.JSX.Element;

export { type Badge, BadgeCard, type BadgeCategory, type BadgeCondition, BadgeCount, BadgeGrid, type BadgeProgress, BadgeProgressBar, type BadgeRarity, type BadgesConfig, type BadgesEvents, BadgesProvider, type BadgesService, BadgesServiceImpl, type BadgesState, type UnlockedBadge, useBadges, useBadgesContext };