A production-ready, zero-dependency TypeScript engine to generate emoji progress bars & terminal animations.

🚀 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 class="tok-string">"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 class="tok-string">"emoji-progress-kit";

const customOutput = custom({
  percentage: 45,
  size: 10,
  completedEmoji: class="tok-string">"🔥",
  remainingEmoji: class="tok-string">"💨",
  spacing: true,
  prefix: class="tok-string">"[Deployment]",
  suffix: class="tok-string">"Processing...",
  showPercentage: true,
  rounded: true
});

console.log(customOutput);
// Output: [Deployment] 🔥 🔥 🔥 🔥 💨 💨 💨 💨 💨 💨 45% Processing...

3. Rapid Developer Presets

typescript
import { gaming, coding, neon, dark } from class="tok-string">"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 class="tok-string">"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 class="tok-string">"react";
import { hearts } from class="tok-string">"emoji-progress-kit";

interface HUDProps {
  healthPoints: number;
}

export const PlayerHealthHUD: React.FC<HUDProps> = ({ healthPoints }) => {
  return (
    <div className=class="tok-string">"player-hud-container" role=class="tok-string">"progressbar" aria-valuenow={healthPoints}>
      <span className=class="tok-string">"hud-label">HP:</span>
      <span className=class="tok-string">"hud-track">{hearts({ percentage: healthPoints, size: 5, showPercentage: true })}</span>
    </div>
  );
};

React Native Native Strings

tsx
import React from class="tok-string">"react";
import { StyleSheet, Text, View } from class="tok-string">"react-native";
import { stars } from class="tok-string">"emoji-progress-kit";

export const ExperienceCard = ({ expPercentage }: { expPercentage: number }) => {
  return (
    <View style={styles.container}>
      <Text style={styles.textTrack}>
        {stars({ percentage: expPercentage, size: 8, showPercentage: false })}
      </Text>
    </View>
  );
};

const styles = StyleSheet.create({
  container: { padding: 12, backgroundColor: class="tok-string">"#121212" },
  textTrack: { fontSize: 18, color: class="tok-string">"#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

Developed for precision UI rendering. Made with ❤️ for developers.