# 🚀 Emoji Progress Kit [![npm version](https://img.shields.io/npm/v/emoji-progress-kit.svg?style=flat-rounded)](https://www.npmjs.com/package/emoji-progress-kit) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript Strict](https://img.shields.io/badge/TypeScript-Strict-blue.svg)](https://www.typescriptlang.org/) [![Bundle Size](https://img.shields.io/bundlephobia/minzip/emoji-progress-kit)](https://bundlephobia.com/package/emoji-progress-kit) A production-ready, zero-dependency, and strictly typed TypeScript engine designed to generate beautiful emoji-based progress bars, terminal health indicators, and CLI dashboard animations. Seamlessly compatible with Node.js, React, React Native, Discord Bots, Electron, Bun, and Deno. --- ## 💎 Core Capabilities * **🔒 Pure & Safe:** Zero third-party dependencies. Immune to supply-chain vulnerabilities. * **🌳 Tree-Shakable:** Architected with atomic functional exports so your bundle only includes what you use. * **📦 Hybrid Interoperability:** Native Dual-compiled support for both ECMAScript Modules (ESM) and CommonJS (CJS). * **🎨 Highly Customizable:** Fine-tune sizing, explicit emoji blocks, padding, custom percentage string overriding, and Right-to-Left (RTL) rendering layouts. * **⚡ High Performance:** Optimized string builders with built-in boundary mathematical clamping (`0-100%`) to prevent UI breaking. --- ## 🛠️ Installation Install via your preferred package manager: ```bash # npm npm install emoji-progress-kit # yarn yarn add emoji-progress-kit # pnpm pnpm add emoji-progress-kit # bun bun add emoji-progress-kit ``` --- ## 🚀 Quick Start Guide ### 1. Basic Engine Rendering ```typescript import { linear, hearts, stars, rainbow } from "emoji-progress-kit"; // Classic Linear Track console.log(linear({ percentage: 70 })); // Output: 📘📘📘📘📘📘📘📙📙📙 // Heart Status Indicator with explicit text metadata console.log(hearts({ percentage: 50, showPercentage: true })); // Output: 💖💖💖💖💖🖤🖤🖤🖤🖤 50% // Sized Star Component console.log(stars({ percentage: 80, size: 5 })); // Output: ⭐⭐⭐⭐⚫ // Dynamic Procedural Rainbow console.log(rainbow({ percentage: 60, size: 6 })); // Output: 🔴🟠🟡🟢🔵🟣 ``` ### 2. Deep Custom Engineering ```typescript import { custom } from "emoji-progress-kit"; const customOutput = custom({ percentage: 45, size: 10, completedEmoji: "🔥", remainingEmoji: "💨", spacing: true, prefix: "[Deployment]", suffix: "Processing...", showPercentage: true, rounded: true }); console.log(customOutput); // Output: [Deployment] 🔥 🔥 🔥 🔥 💨 💨 💨 💨 💨 💨 45% Processing... ``` ### 3. Rapid Developer Presets ```typescript import { gaming, coding, neon, dark } from "emoji-progress-kit"; console.log(gaming({ percentage: 70 })); // 🎮🎮🎮🎮🎮🎮🎮🕹️🕹️🕹️ console.log(coding({ percentage: 30 })); // 💻💻💻📁📁📁📁📁📁📁 console.log(neon({ percentage: 90 })); // ⚡⚡⚡⚡⚡⚡⚡⚡⚡🌌 console.log(dark({ percentage: 50 })); // 😈😈😈😈😈💀💀💀💀💀 ``` ### 4. Terminal Animation Tickers (CLI Implementation) Animations return fully structured schema metadata containing continuous raw frame arrays and strict timing intervals so you can power low-overhead event loops manually. ```typescript import { spinner } from "emoji-progress-kit"; const clockAnim = spinner(); let currentFrame = 0; setInterval(() => { process.stdout.write(`\r[Engine Status] Loading System Dependencies ${clockAnim.frames[currentFrame % clockAnim.frames.length]}`); currentFrame++; }, clockAnim.interval); ``` --- ## 📋 Comprehensive API Specification ### Progress Generators `linear()`, `circle()`, `dots()`, `hearts()`, `stars()`, `battery()`, `loading()`, `rainbow()`, `custom()` All core engine interfaces absorb structural attributes satisfying the strict `ProgressOptions` model contract: | Variable Option | Data Type | Default Fallback | Technical Description | | --- | --- | --- | --- | | `percentage` | `number` | *Required* | Absolute input runtime metric. Built-in `clamp` enforces bounds between `0` and `100`. | | `size` | `number` | `10` | Grid block allocation footprint determining total character sequence width. | | `completedEmoji` | `string` | *Context Dependent* | Visual asset assigned to fill the positive execution track space. | | `remainingEmoji` | `string` | *Context Dependent* | Visual asset assigned to fill the negative execution track space. | | `showPercentage` | `boolean` | `false` | Dynamically appends formatted string metrics trailing the layout structure. | | `rounded` | `boolean` | `true` | When true, flattens floating decimals to the nearest whole integer value. | | `spacing` | `boolean` | `false` | Explicitly introduces formatting spacing parameters between each emoji symbol block. | | `reverse` | `boolean` | `false` | Inverts allocation layout directions causing completed pools to scale right-to-left. | | `rtl` | `boolean` | `false` | Structural layout mirroring to accommodate multi-language text parsing contexts. | | `prefix` | `string` | `undefined` | Prepends immutable contextual text arrays directly before the track. | | `suffix` | `string` | `undefined` | Appends immutable contextual text arrays directly after the track metadata. | | `customFormatter` | `Function` | `undefined` | Custom callback intercept hook `(percent: number) => string` to rewrite output numbers. | --- ## 🌐 Universal Environment Integrations ### React Architecture Hookups ```tsx import React from "react"; import { hearts } from "emoji-progress-kit"; interface HUDProps { healthPoints: number; } export const PlayerHealthHUD: React.FC = ({ healthPoints }) => { return (

HP: {hearts({ percentage: healthPoints, size: 5, showPercentage: true })}

); }; ``` ### React Native Native Strings ```tsx import React from "react"; import { StyleSheet, Text, View } from "react-native"; import { stars } from "emoji-progress-kit"; export const ExperienceCard = ({ expPercentage }: { expPercentage: number }) => { return ( {stars({ percentage: expPercentage, size: 8, showPercentage: false })} ); }; const styles = StyleSheet.create({ container: { padding: 12, backgroundColor: "#121212" }, textTrack: { fontSize: 18, color: "#ffffff" } }); ``` --- ## ⚙️ Execution Environments & Compatibility * **Node.js:** `>=16.0.0` * **Browsers:** All modern evergreen runtimes natively supporting ECMAScript 2022+ primitives. * **Runtimes:** Fully supported and validated on **Bun** and **Deno** systems natively. --- ## 📄 License & Legalities Distributed fully under the operational criteria of the open-source **MIT License**. Check out the detailed `LICENSE` asset file for verified legal coverage clauses. --- ## 🎨 System Authorship Maintained with dedication by **Dream Mythic Studio**. Explore engineering updates and package code systems at: [GitHub Source Core](https://github.com/vaibhavdhake123/emoji-progress-kit) --- Developed for precision UI rendering. Made with ❤️ for developers.

Packages

Emoji Progress Kit

Express ResForge