questro/dist/levels/index.d.ts

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 * as react_jsx_runtime from 'react/jsx-runtime';
import React from 'react';
import { S as StorageAdapter } from '../types-B4P_iNGe.js';

type LevelFormula = 'linear' | 'exponential' | 'fibonacci' | 'rpg' | 'custom';
type LevelConfig = {
    userId: string;
    formula?: LevelFormula;
    baseXP?: number;
    scalingFactor?: number;
    maxLevel?: number;
    customFormula?: (level: number) => number;
    onLevelUp?: (event: LevelUpEvent) => void;
    onXPGain?: (amount: number, totalXP: number) => void;
};
type LevelData = {
    level: number;
    currentXP: number;
    totalXP: number;
    xpForCurrentLevel: number;
    xpForNextLevel: number;
    xpToLevelUp: number;
    progress: number;
};
type LevelUpEvent = {
    previousLevel: number;
    newLevel: number;
    totalXP: number;
    timestamp: number;
    rewards?: {
        badge?: string;
        currency?: Record<string, number>;
        items?: string[];
    };
};
type XPTransaction = {
    id: string;
    amount: number;
    balance: number;
    reason?: string;
    timestamp: number;
    levelBefore: number;
    levelAfter: number;
};
type LevelsState = {
    userId: string;
    totalXP: number;
    level: number;
    levelHistory: LevelUpEvent[];
    xpHistory: XPTransaction[];
    lastUpdated: number;
};

type LevelsContextValue = {
    levelData: LevelData;
    xpHistory: XPTransaction[];
    levelHistory: LevelUpEvent[];
    addXP: (amount: number, reason?: string) => void;
    removeXP: (amount: number, reason?: string) => void;
    setLevel: (level: number) => void;
    reset: () => void;
    getXPForLevel: (level: number) => number;
    getLevelFromXP: (xp: number) => number;
};
type LevelsProviderProps = {
    children: React.ReactNode;
    config: LevelConfig;
    storage?: StorageAdapter<LevelsState>;
};
declare function LevelsProvider({ children, config, storage }: LevelsProviderProps): react_jsx_runtime.JSX.Element | null;
declare function useLevels(): LevelsContextValue;

declare class LevelsService {
    private state;
    private config;
    private listeners;
    constructor(config: LevelConfig, initialState?: LevelsState);
    private createInitialState;
    getLevelData(): LevelData;
    addXP(amount: number, reason?: string): XPTransaction;
    removeXP(amount: number, reason?: string): XPTransaction;
    setLevel(level: number): void;
    reset(): void;
    getXPForLevel(level: number): number;
    getLevelFromXP(xp: number): number;
    getState(): LevelsState;
    getXPHistory(): XPTransaction[];
    getLevelHistory(): LevelUpEvent[];
    subscribe(listener: () => void): () => void;
    private handleLevelUp;
    private notifyListeners;
}

declare const XP_FORMULAS: Record<Exclude<LevelFormula, 'custom'>, (level: number, baseXP: number, scalingFactor: number) => number>;
declare function calculateXPForLevel(level: number, formula: LevelFormula, baseXP?: number, scalingFactor?: number, customFormula?: (level: number) => number): number;
declare function calculateLevelFromXP(totalXP: number, formula: LevelFormula, baseXP?: number, scalingFactor?: number, customFormula?: (level: number) => number, maxLevel?: number): number;
declare function calculateLevelProgress(totalXP: number, currentLevel: number, formula: LevelFormula, baseXP?: number, scalingFactor?: number, customFormula?: (level: number) => number): {
    currentXP: number;
    xpToLevelUp: number;
    progress: number;
};

type LevelDisplayProps = {
    showXP?: boolean;
    showPercentage?: boolean;
    className?: string;
    children?: (data: {
        level: number;
        currentXP: number;
        xpToLevelUp: number;
        progress: number;
    }) => React.ReactNode;
};
declare function LevelDisplay({ showXP, showPercentage, className, children, }: LevelDisplayProps): react_jsx_runtime.JSX.Element;

type XPBarProps = {
    height?: string;
    showPercentage?: boolean;
    showXP?: boolean;
    animated?: boolean;
    className?: string;
    fillClassName?: string;
    children?: (data: {
        progress: number;
        currentXP: number;
        xpToLevelUp: number;
        level: number;
    }) => React.ReactNode;
};
declare function XPBar({ height, showPercentage, showXP, animated, className, fillClassName, children, }: XPBarProps): react_jsx_runtime.JSX.Element;

export { type LevelConfig, type LevelData, LevelDisplay, type LevelDisplayProps, type LevelFormula, type LevelUpEvent, LevelsProvider, type LevelsProviderProps, LevelsService, type LevelsState, XPBar, type XPBarProps, type XPTransaction, XP_FORMULAS, calculateLevelFromXP, calculateLevelProgress, calculateXPForLevel, useLevels };