fuelex-leaderboard 1.0.0

package/README.md

@@ -0,0 +1,191 @@
+# Fuelex Leaderboard
+
+<div align="center">
+
+![Fuelex Banner](https://fuelex-bot.dev/banner.png)
+
+**Premium Discord Leaderboard UI Package**
+
+[![npm version](https://img.shields.io/npm/v/fuelex-leaderboard.svg?style=flat-square&color=FFD700)](https://www.npmjs.com/package/fuelex-leaderboard)
+[![License](https://img.shields.io/badge/license-MIT-yellow.svg?style=flat-square)](LICENSE)
+[![Discord](https://img.shields.io/badge/Discord-Fuelex-FFD700?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/fuelex)
+
+*High-quality, customizable leaderboard image generator for Discord bots*
+
+</div>
+
+---
+
+## ✨ Features
+
+- 🎨 **Premium Black & Yellow Theme** - Sleek, modern design with neon glow effects
+- 🏆 **Tier-based Rank Styling** - Gold, Silver, Bronze gradients for top 3
+- 📊 **Multiple Stat Types** - Voice, XP, Messages, Invites, Economy, Levels
+- ⚡ **High Performance** - Built with `@napi-rs/canvas` for native speed
+- 🔧 **Fully Customizable** - Easy to configure and extend
+- 📱 **Discord Optimized** - Perfect dimensions for embeds and messages
+
+---
+
+## 📦 Installation
+
+```bash
+npm install fuelex-leaderboard
+```
+
+---
+
+## 🚀 Quick Start
+
+```javascript
+const { LeaderboardCard } = require('fuelex-leaderboard');
+const fs = require('fs');
+
+// Create a voice leaderboard
+const leaderboard = new LeaderboardCard({
+    type: 'voice',
+    title: 'Voice Leaderboard',
+    users: [
+        { rank: 1, userId: '123', username: 'DragonSlayer', value: 43200, isActive: true },
+        { rank: 2, userId: '456', username: 'NightWolf', value: 38500, isActive: true },
+        { rank: 3, userId: '789', username: 'PhoenixRider', value: 32100, isActive: false },
+        // ... more users
+    ],
+    rowCount: 10,
+    footer: 'fuelex-bot.dev'
+});
+
+// Generate the image
+const buffer = await leaderboard.render();
+fs.writeFileSync('leaderboard.png', buffer);
+```
+
+---
+
+## 📋 Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `type` | `string` | `'xp'` | Leaderboard type: `voice`, `xp`, `messages`, `invites`, `economy`, `levels` |
+| `title` | `string` | Auto-generated | Custom title for the leaderboard |
+| `users` | `Array` | `[]` | Array of user objects |
+| `rowCount` | `number` | `10` | Number of rows to display (5, 10, 15, 20) |
+| `footer` | `string` | `null` | Optional footer text |
+| `showHeader` | `boolean` | `true` | Whether to show the header section |
+| `showAvatars` | `boolean` | `true` | Whether to display user avatars |
+
+---
+
+## 👤 User Object
+
+```javascript
+{
+    rank: 1,              // User's rank position (1-indexed)
+    userId: '123456789',  // Unique identifier
+    username: 'Player1',  // Display name
+    value: 12345,         // Stat value (formatted based on type)
+    avatar: 'https://...', // Optional avatar URL
+    isActive: true        // Optional status indicator
+}
+```
+
+---
+
+## 🎨 Stat Types
+
+| Type | Icon | Value Format |
+|------|------|--------------|
+| `voice` | 🔊 Speaker | Duration (12h 34m) |
+| `xp` | ⭐ Star | Number with XP suffix |
+| `messages` | 💬 Message | Plain number |
+| `invites` | 👥 User | Plain number |
+| `economy` | 💰 Coin | Currency format ($1,234) |
+| `levels` | 🏆 Trophy | Level prefix (Lv. 50) |
+
+---
+
+## 🖼️ Output Formats
+
+```javascript
+// PNG (default, best for Discord)
+const pngBuffer = await leaderboard.render();
+
+// JPEG (smaller file size)
+const jpegBuffer = await leaderboard.renderJPEG(90); // quality: 0-100
+```
+
+---
+
+## 🎯 Discord.js Integration
+
+```javascript
+const { AttachmentBuilder } = require('discord.js');
+const { LeaderboardCard } = require('fuelex-leaderboard');
+
+async function sendLeaderboard(interaction) {
+    const leaderboard = new LeaderboardCard({
+        type: 'voice',
+        users: await fetchTopUsers(),
+        rowCount: 10
+    });
+    
+    const buffer = await leaderboard.render();
+    const attachment = new AttachmentBuilder(buffer, { name: 'leaderboard.png' });
+    
+    await interaction.reply({ files: [attachment] });
+}
+```
+
+---
+
+## 🎨 Color Palette
+
+| Element | Color | Hex |
+|---------|-------|-----|
+| Background | Deep Matte Black | `#0A0A0A` |
+| Card | Charcoal | `#1A1A1A` |
+| Neon Yellow | Primary Accent | `#FFEA00` |
+| Gold (#1) | Gradient | `#FFD700 → #FFA500` |
+| Silver (#2) | Muted | `#C0C0C0` |
+| Bronze (#3) | Warm | `#CD7F32` |
+
+---
+
+## 📁 Project Structure
+
+```
+fuelex-leaderboard/
+├── src/
+│   ├── index.js           # Main entry point
+│   ├── core/
+│   │   └── theme.js       # Colors, constants, utilities
+│   ├── components/
+│   │   ├── LeaderboardCard.js
+│   │   ├── RankBadge.js
+│   │   ├── StatIcon.js
+│   │   └── UserRow.js
+│   └── utils/
+│       ├── effects.js     # Glow, shadows, gradients
+│       └── fonts.js       # Font management
+├── examples/
+│   └── basic.js           # Usage examples
+├── output/                 # Generated images
+├── package.json
+└── README.md
+```
+
+---
+
+## 🔗 Links
+
+- **Website**: [fuelex-bot.dev](https://fuelex-bot.dev)
+- **Discord**: [Join Server](https://discord.gg/fuelex)
+- **GitHub**: [fuelex/fuelex-leaderboard](https://github.com/fuelex/fuelex-leaderboard)
+
+---
+
+<div align="center">
+
+**Built with 💛 by the Fuelex Team**
+
+</div>

package/examples/basic.js

@@ -0,0 +1,137 @@
+/**
+ * Fuelex Leaderboard - Example Usage
+ * Demonstrates generating leaderboard images
+ */
+
+const { LeaderboardCard } = require('../src/index');
+const fs = require('fs');
+const path = require('path');
+
+// Sample user data
+const sampleUsers = [
+    { rank: 1, userId: '1', username: 'DragonSlayer', value: 43200, isActive: true },
+    { rank: 2, userId: '2', username: 'NightWolf', value: 38500, isActive: true },
+    { rank: 3, userId: '3', username: 'PhoenixRider', value: 32100, isActive: false },
+    { rank: 4, userId: '4', username: 'ShadowHunter', value: 28900, isActive: true },
+    { rank: 5, userId: '5', username: 'CrystalMage', value: 25400, isActive: true },
+    { rank: 6, userId: '6', username: 'StormBringer', value: 21800, isActive: false },
+    { rank: 7, userId: '7', username: 'FrostKnight', value: 18200, isActive: true },
+    { rank: 8, userId: '8', username: 'BlazeMaster', value: 15600, isActive: true },
+    { rank: 9, userId: '9', username: 'VoidWalker', value: 12300, isActive: false },
+    { rank: 10, userId: '10', username: 'ThunderGod', value: 9800, isActive: true }
+];
+
+async function generateExamples() {
+    const outputDir = path.join(__dirname, '../output');
+
+    // Create output directory if it doesn't exist
+    if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true });
+    }
+
+    console.log('🎨 Generating Fuelex Leaderboard examples...\n');
+
+    // Generate Voice Leaderboard
+    console.log('📊 Creating Voice Leaderboard...');
+    const voiceLeaderboard = new LeaderboardCard({
+        type: 'voice',
+        title: 'Voice Leaderboard',
+        users: sampleUsers,
+        rowCount: 10,
+        footer: 'fuelex-bot.dev'
+    });
+
+    const voiceBuffer = await voiceLeaderboard.render();
+    fs.writeFileSync(path.join(outputDir, 'voice_leaderboard.png'), voiceBuffer);
+    console.log('   ✓ Saved: voice_leaderboard.png');
+
+    // Generate XP Leaderboard
+    console.log('📊 Creating XP Leaderboard...');
+    const xpLeaderboard = new LeaderboardCard({
+        type: 'xp',
+        title: 'XP Leaderboard',
+        users: sampleUsers.map(u => ({ ...u, value: u.value * 10 })),
+        rowCount: 10,
+        footer: 'fuelex-bot.dev'
+    });
+
+    const xpBuffer = await xpLeaderboard.render();
+    fs.writeFileSync(path.join(outputDir, 'xp_leaderboard.png'), xpBuffer);
+    console.log('   ✓ Saved: xp_leaderboard.png');
+
+    // Generate Economy Leaderboard
+    console.log('📊 Creating Economy Leaderboard...');
+    const economyLeaderboard = new LeaderboardCard({
+        type: 'economy',
+        title: 'Richest Members',
+        users: sampleUsers.map(u => ({ ...u, value: u.value * 100 })),
+        rowCount: 10,
+        footer: 'fuelex-bot.dev'
+    });
+
+    const economyBuffer = await economyLeaderboard.render();
+    fs.writeFileSync(path.join(outputDir, 'economy_leaderboard.png'), economyBuffer);
+    console.log('   ✓ Saved: economy_leaderboard.png');
+
+    // Generate Messages Leaderboard
+    console.log('📊 Creating Messages Leaderboard...');
+    const messagesLeaderboard = new LeaderboardCard({
+        type: 'messages',
+        title: 'Most Active Chatters',
+        users: sampleUsers.map(u => ({ ...u, value: Math.floor(u.value / 10) })),
+        rowCount: 10,
+        footer: 'fuelex-bot.dev'
+    });
+
+    const messagesBuffer = await messagesLeaderboard.render();
+    fs.writeFileSync(path.join(outputDir, 'messages_leaderboard.png'), messagesBuffer);
+    console.log('   ✓ Saved: messages_leaderboard.png');
+
+    // Generate Invites Leaderboard
+    console.log('📊 Creating Invites Leaderboard...');
+    const invitesLeaderboard = new LeaderboardCard({
+        type: 'invites',
+        title: 'Top Inviters',
+        users: sampleUsers.map(u => ({ ...u, value: Math.floor(u.value / 1000) })),
+        rowCount: 10,
+        footer: 'fuelex-bot.dev'
+    });
+
+    const invitesBuffer = await invitesLeaderboard.render();
+    fs.writeFileSync(path.join(outputDir, 'invites_leaderboard.png'), invitesBuffer);
+    console.log('   ✓ Saved: invites_leaderboard.png');
+
+    // Generate Levels Leaderboard
+    console.log('📊 Creating Levels Leaderboard...');
+    const levelsLeaderboard = new LeaderboardCard({
+        type: 'levels',
+        title: 'Top Levels',
+        users: sampleUsers.map((u, i) => ({ ...u, value: 100 - i * 8 })),
+        rowCount: 10,
+        footer: 'fuelex-bot.dev'
+    });
+
+    const levelsBuffer = await levelsLeaderboard.render();
+    fs.writeFileSync(path.join(outputDir, 'levels_leaderboard.png'), levelsBuffer);
+    console.log('   ✓ Saved: levels_leaderboard.png');
+
+    // Generate Compact (5 rows)
+    console.log('📊 Creating Compact Leaderboard (5 rows)...');
+    const compactLeaderboard = new LeaderboardCard({
+        type: 'xp',
+        title: 'Top 5 Players',
+        users: sampleUsers.slice(0, 5),
+        rowCount: 5,
+        footer: 'fuelex-bot.dev'
+    });
+
+    const compactBuffer = await compactLeaderboard.render();
+    fs.writeFileSync(path.join(outputDir, 'compact_leaderboard.png'), compactBuffer);
+    console.log('   ✓ Saved: compact_leaderboard.png');
+
+    console.log('\n✨ All examples generated successfully!');
+    console.log(`📁 Output directory: ${outputDir}`);
+}
+
+// Run examples
+generateExamples().catch(console.error);

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "fuelex-leaderboard",
+  "version": "1.0.0",
+  "description": "Premium Discord leaderboard UI generator for Fuelex Bot - Black & Yellow theme",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "node test/generate.js",
+    "example": "node examples/basic.js"
+  },
+  "keywords": [
+    "discord",
+    "leaderboard",
+    "fuelex",
+    "canvas",
+    "image",
+    "generator",
+    "bot",
+    "voice",
+    "xp",
+    "levels",
+    "economy"
+  ],
+  "author": "Fuelex Team",
+  "license": "MIT",
+  "homepage": "https://fuelex-bot.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fuelex/fuelex-leaderboard"
+  },
+  "dependencies": {
+    "@napi-rs/canvas": "^0.1.65"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/components/LeaderboardCard.js

@@ -0,0 +1,269 @@
+/**
+ * Fuelex Leaderboard - Main Leaderboard Card Component
+ * Premium Discord leaderboard image generator
+ */
+
+const { createCanvas, loadImage } = require('@napi-rs/canvas');
+const { COLORS, SIZES, getStatConfig } = require('../core/theme');
+const { drawRoundedRect, applyShadow, clearShadow } = require('../utils/effects');
+const { registerFonts, getFont } = require('../utils/fonts');
+const { drawUserRow } = require('./UserRow');
+
+/**
+ * LeaderboardCard - Main class for generating leaderboard images
+ */
+class LeaderboardCard {
+    /**
+     * Create a new LeaderboardCard
+     * @param {object} options - Leaderboard options
+     * @param {string} options.type - Leaderboard type (voice, xp, messages, invites, economy, levels)
+     * @param {string} [options.title] - Custom title (auto-generated if not provided)
+     * @param {Array} options.users - Array of user data
+     * @param {number} [options.rowCount=10] - Number of rows to display
+     * @param {string} [options.footer] - Footer text
+     * @param {boolean} [options.showHeader=true] - Whether to show the header
+     * @param {boolean} [options.showAvatars=true] - Whether to show user avatars
+     */
+    constructor(options = {}) {
+        this.type = options.type || 'xp';
+        this.title = options.title || this._generateTitle();
+        this.users = options.users || [];
+        this.rowCount = options.rowCount || 10;
+        this.footer = options.footer || null;
+        this.showHeader = options.showHeader !== false;
+        this.showAvatars = options.showAvatars !== false;
+
+        // Calculate dimensions
+        this.width = SIZES.cardWidth;
+        this.headerHeight = this.showHeader ? 60 : 0;
+        this.footerHeight = this.footer ? 40 : 0;
+        this.rowHeight = SIZES.rowHeight;
+        this.rowGap = SIZES.rowGap;
+        this.padding = SIZES.cardPadding;
+
+        // Register fonts on instantiation
+        registerFonts();
+    }
+
+    /**
+     * Generate default title based on type
+     * @returns {string} Generated title
+     * @private
+     */
+    _generateTitle() {
+        const statConfig = getStatConfig(this.type);
+        return `${statConfig.label} Leaderboard`;
+    }
+
+    /**
+     * Calculate total canvas height
+     * @returns {number} Canvas height
+     * @private
+     */
+    _calculateHeight() {
+        const displayCount = Math.min(this.users.length, this.rowCount);
+        const rowsHeight = displayCount * this.rowHeight + (displayCount - 1) * this.rowGap;
+        return this.padding * 2 + this.headerHeight + rowsHeight + this.footerHeight;
+    }
+
+    /**
+     * Draw the header section
+     * @param {CanvasRenderingContext2D} ctx - Canvas context
+     * @private
+     */
+    _drawHeader(ctx) {
+        if (!this.showHeader) return;
+
+        const statConfig = getStatConfig(this.type);
+
+        // Draw title
+        ctx.font = getFont(SIZES.headerFontSize, 'bold');
+        ctx.textAlign = 'left';
+        ctx.textBaseline = 'middle';
+
+        // Title with glow
+        ctx.save();
+        ctx.shadowColor = COLORS.glowYellow;
+        ctx.shadowBlur = 10;
+        ctx.fillStyle = COLORS.goldenYellow;
+        ctx.fillText(this.title, this.padding, this.padding + 30);
+        ctx.restore();
+
+        // Draw type indicator icon
+        const { drawIcon } = require('./StatIcon');
+        drawIcon(
+            ctx,
+            statConfig.icon,
+            this.width - this.padding - 30,
+            this.padding + 18,
+            24,
+            COLORS.neonYellow,
+            true
+        );
+    }
+
+    /**
+     * Draw the footer section
+     * @param {CanvasRenderingContext2D} ctx - Canvas context
+     * @param {number} y - Y position for footer
+     * @private
+     */
+    _drawFooter(ctx, y) {
+        if (!this.footer) return;
+
+        ctx.font = getFont(14, 'regular');
+        ctx.textAlign = 'center';
+        ctx.textBaseline = 'middle';
+        ctx.fillStyle = COLORS.textMuted;
+        ctx.fillText(this.footer, this.width / 2, y + 20);
+    }
+
+    /**
+     * Draw the main background
+     * @param {CanvasRenderingContext2D} ctx - Canvas context
+     * @param {number} height - Canvas height
+     * @private
+     */
+    _drawBackground(ctx, height) {
+        // Main background
+        ctx.fillStyle = COLORS.primaryBg;
+        ctx.fillRect(0, 0, this.width, height);
+
+        // Subtle gradient overlay
+        const gradient = ctx.createLinearGradient(0, 0, 0, height);
+        gradient.addColorStop(0, 'rgba(255, 215, 0, 0.03)');
+        gradient.addColorStop(0.5, 'transparent');
+        gradient.addColorStop(1, 'rgba(255, 215, 0, 0.02)');
+        ctx.fillStyle = gradient;
+        ctx.fillRect(0, 0, this.width, height);
+
+        // Outer border glow
+        ctx.save();
+        ctx.strokeStyle = COLORS.goldenYellow;
+        ctx.lineWidth = 2;
+        ctx.shadowColor = COLORS.glowGold;
+        ctx.shadowBlur = 15;
+        ctx.beginPath();
+        ctx.roundRect(1, 1, this.width - 2, height - 2, 16);
+        ctx.stroke();
+        ctx.restore();
+    }
+
+    /**
+     * Load avatar images for users
+     * @returns {Promise<Map>} Map of userId to loaded image
+     * @private
+     */
+    async _loadAvatars() {
+        const avatarMap = new Map();
+
+        if (!this.showAvatars) return avatarMap;
+
+        const loadPromises = this.users.slice(0, this.rowCount).map(async (user) => {
+            if (user.avatar) {
+                try {
+                    const img = await loadImage(user.avatar);
+                    avatarMap.set(user.userId, img);
+                } catch (e) {
+                    // Failed to load avatar, will render without it
+                }
+            }
+        });
+
+        await Promise.all(loadPromises);
+        return avatarMap;
+    }
+
+    /**
+     * Render the leaderboard to a canvas buffer
+     * @returns {Promise<Buffer>} PNG image buffer
+     */
+    async render() {
+        const height = this._calculateHeight();
+        const canvas = createCanvas(this.width, height);
+        const ctx = canvas.getContext('2d');
+
+        // Draw background
+        this._drawBackground(ctx, height);
+
+        // Draw header
+        this._drawHeader(ctx);
+
+        // Load avatars
+        const avatarMap = await this._loadAvatars();
+
+        // Draw user rows
+        const startY = this.padding + this.headerHeight;
+        const rowWidth = this.width - this.padding * 2;
+        const displayUsers = this.users.slice(0, this.rowCount);
+
+        for (let i = 0; i < displayUsers.length; i++) {
+            const user = displayUsers[i];
+            const rowY = startY + i * (this.rowHeight + this.rowGap);
+            const avatarImg = avatarMap.get(user.userId) || null;
+
+            await drawUserRow(
+                ctx,
+                user,
+                this.padding,
+                rowY,
+                rowWidth,
+                this.rowHeight,
+                this.type,
+                avatarImg
+            );
+        }
+
+        // Draw footer
+        const footerY = startY + displayUsers.length * (this.rowHeight + this.rowGap);
+        this._drawFooter(ctx, footerY);
+
+        return canvas.toBuffer('image/png');
+    }
+
+    /**
+     * Render to JPEG format
+     * @param {number} quality - JPEG quality (0-100)
+     * @returns {Promise<Buffer>} JPEG image buffer
+     */
+    async renderJPEG(quality = 90) {
+        const height = this._calculateHeight();
+        const canvas = createCanvas(this.width, height);
+        const ctx = canvas.getContext('2d');
+
+        // Draw everything
+        this._drawBackground(ctx, height);
+        this._drawHeader(ctx);
+
+        const avatarMap = await this._loadAvatars();
+        const startY = this.padding + this.headerHeight;
+        const rowWidth = this.width - this.padding * 2;
+        const displayUsers = this.users.slice(0, this.rowCount);
+
+        for (let i = 0; i < displayUsers.length; i++) {
+            const user = displayUsers[i];
+            const rowY = startY + i * (this.rowHeight + this.rowGap);
+            const avatarImg = avatarMap.get(user.userId) || null;
+
+            await drawUserRow(ctx, user, this.padding, rowY, rowWidth, this.rowHeight, this.type, avatarImg);
+        }
+
+        const footerY = startY + displayUsers.length * (this.rowHeight + this.rowGap);
+        this._drawFooter(ctx, footerY);
+
+        return canvas.toBuffer('image/jpeg', { quality: quality / 100 });
+    }
+
+    /**
+     * Get the canvas dimensions
+     * @returns {object} Width and height
+     */
+    getDimensions() {
+        return {
+            width: this.width,
+            height: this._calculateHeight()
+        };
+    }
+}
+
+module.exports = { LeaderboardCard };