🖥️ @trap_stevo/terminal-plus

Transform your CLI into a visually striking, feature-rich command layer.
Blend animated gradients, stylish badges, dynamic progress bars, sleek tables, and precision formatting utilities — engineered for legendary terminal output.

🚀 Features

• 🔆 Animated gradient text and smooth-moving animations
• 🏷️ Stylish, icon-enhanced terminal badges
• 📊 Interactive multi-task progress bars with paging
• 📋 Sleek auto-formatted console tables with border styles and gradients
• 📄 Paginated views with in-place redraw
• 🧭 Interactive, width-aware breadcrumbs
• 🗂️ Interactive tabs
• 🔎 Searchable selectors and autocomplete
• 📜 Interactive lists and tables
• ⌨️ Input fields and terminal forms
• 🌳 Hierarchical tree views
• 🪟 Modals, panels, panel layouts, and dashboards
• 📡 Status bars and key-hint bars
• 🎨 Color formatting utilities
• 🔔 Toast notifications and live regions
• 🧰 Command palettes and log views
• 🖥️ Terminal screen and cursor management
• 🔗 Attach dynamic followers to animations or base content
• 🧠 Byte and time formatting utilities

⚙️ System Requirements

| Requirement | Version | |----------------|--------------------| | Node.js | ≥ 19.x | | npm | ≥ 9.x (recommended)| | OS | Windows, macOS, Linux |

📐 API Overview

| Method | Description | Async | |---|---|:---:| | constructor(options) | Initializes a new TerminalPlus instance with optional config | ❌ | | log(message, type, typeOptions) | Logs a styled message with timestamp | ❌ | | printGradient(text, colors) | Prints gradient-colored static text | ❌ | | printMovingGradient(text, colors, interval) | Displays animated gradient text | ❌ | | printColor(text, opts) | Returns styled text with custom color formatting | ❌ | | printBadge(label, opts) | Prints a stylized badge directly to the terminal | ❌ | | getBadge(label, opts) | Returns a rendered badge string | ❌ | | drawDivider(type, position, colors, content, width) | Renders a gradient divider or sci-fi frame | ❌ | | createTable(data, opts) | Renders a formatted, stylized console table | ❌ | | createProgressBar(tasks, opts) | Creates the multi-task console progress manager | ❌ | | createSpinner(label, opts) | Creates and starts an animated terminal spinner | ❌ | | createPaginatedView(items, opts) | Creates a paginated view with controlled redraw and navigation | ❌ | | createLiveRegion(opts) | Creates a region intended for repeatedly updated terminal content | ❌ | | createInteractiveList(items, opts) | Creates an interactive list component | ❌ | | createInteractiveTable(rows, opts) | Creates an interactive table component | ❌ | | createSearchableSelector(items, opts) | Creates a filterable/searchable selector | ❌ | | createInputField(opts) | Creates an interactive input field | ❌ | | createAutocomplete(values, opts) | Creates an autocomplete helper | ❌ | | createTree(opts) | Creates a hierarchical terminal tree | ❌ | | createBreadcrumb(opts) | Creates a width-aware, optionally interactive breadcrumb | ❌ | | createStatusBar(opts) | Creates a terminal status bar | ❌ | | createKeyHintBar(opts) | Creates a compact keyboard-hint bar | ❌ | | createTabs(tabs, opts) | Creates stateful terminal tabs | ❌ | | createModal(opts) | Creates a modal-style terminal view | ❌ | | createCommandPalette(commands, opts) | Creates a searchable command palette | ❌ | | createProgressGroup(tasks, opts) | Creates a grouped concurrent-progress display | ❌ | | createLogView(opts) | Creates a structured terminal log view | ❌ | | createDashboard(opts) | Creates a dashboard container | ❌ | | createPanel(opts) | Creates a styled terminal panel | ❌ | | createPanelLayout(opts) | Creates a multi-panel layout manager | ❌ | | createForm(fields, opts) | Creates an interactive multi-field terminal form | ❌ | | createScreen(stream) | Creates terminal screen/cursor management utilities | ❌ | | notify(message, opts) | Displays a terminal toast notification | ❌ | | attachFollower(base, content, opts) | Dynamically renders content below or inline with animation/content | ✅ | | setDefaultGradient(gradient) | Updates the globally used fallback gradient colors | ❌ | | formatBytes(size, dynamicUnits) | Converts bytes to a readable value with appropriate units | ❌ | | formatSeconds(seconds) | Converts seconds to a readable time value | ❌ |

---------------------------|------------------------------------------------------------------------|:-----:| | constructor(options) | Initializes a new TerminalPlus instance with optional config | ❌ | | log(message, type) | Logs a styled message with timestamp | ❌ | | printGradient(text) | Prints gradient-colored static text to the terminal | ❌ | | printMovingGradient(text, colors, interval) | Displays animated gradient text | ❌ | | printColor(text, opts) | Returns styled text with custom color formatting | ❌ | | printBadge(label, opts) | Prints a stylized badge directly to the terminal | ❌ | | getBadge(label, opts) | Returns the badge as a string (no printing) | ❌ | | drawDivider(type, position, colors, content, width) | Renders a gradient divider line or sci-fi frame | ❌ | | createTable(data, opts) | Renders a formatted, stylized console table | ❌ | | createProgressBar(tasks = [], options = {}) | Displays a multi-task progress bar system | ❌ | | attachFollower(base, content, options = {}) | Dynamically renders content below or inline with an animation | ✅ | | setDefaultGradient(gradient) | Updates the globally used fallback gradient colors | ❌ | | formatBytes(size) | Converts bytes to a readable string with appropriate units | ❌ | | formatSeconds(seconds) | Converts seconds to a hh:mm:ss formatted string | ❌ |

🧰 Methods Overview

constructor(options = {}) — Sync

Initializes the TerminalPlus instance.

Options:

• gradientSpeed (number): Speed of moving gradient (default 100)
• defaultGradient (string[]): Default gradient colors (default ["#00ffff", "#1a73e8"])

log(message, type = "info", typeOptions = {}) — Sync

Log a timestamped message with optional styles.

Parameters:

• message: String to print
• type: "info" | "warn" | "error" | "success" | "debug"
• typeOptions: Override default chalk styles

printGradient(text, colors = this.options.defaultGradient, interval = this.options.gradientSpeed) — Sync

Prints a static gradient text to console.

printMovingGradient(text, colors, interval) — Sync

Returns a moving gradient animation object.

Returns: animation with .start() and .stop() methods

printColor(text, options = {}) — Sync

Returns colored string using inline styles.

Options:

• textColor: hex or color keyword
• backgroundColor: hex or color keyword
• bold, italic, underline etc.

printBadge(label, options = {}) — Sync

Prints a styled badge to the console.

getBadge(label, options = {}) — Sync

Returns the badge string (instead of printing).

Options:

• icon: prepended icon
• textColor, backgroundColor
• gradient: [start, end]
• padding, rounded

🧱 drawDivider(type, position, colors, content, width) — Sync

Draws a gradient divider line or a sci-fi style framed section.

Parameters:

• type (string): "default", "arrow", or "sci-frame" (default: "default")
• position (string|null): "top", "bottom", or null (only applies to "sci-frame")
• colors (string[]): Gradient color pair (default: ["#273140", "#143857"])
• content (string|null): Optional string or pattern to use instead of default line
• width (number): Total width of the divider (default: 116)

// Default sleek divider
terminal.drawDivider();

// Arrow-style divider
terminal.drawDivider("arrow", null, ["#1a3c78", "#1e607e"]);

// Framed section with header
terminal.drawDivider("sci-frame", "top");
terminal.drawDivider("sci-frame", null, ["#1a212b", "#2b7fc5"], " SUPERCL SESSION ", 100);
terminal.drawDivider("sci-frame", "bottom");

// Custom pattern divider
terminal.drawDivider("custom", null, ["#1a3c78", "#338ba8"], "~*~".repeat(30), 120);

createTable(data, options = {}) — Sync

Renders an auto-aligned styled table.

Parameters:

• data: Array of row objects
• options:
  • columnNames: Object map for column labels
  • columnOrder: Array to define column order
  • padding: Cell padding
  • borderStyle: "solid" | "double" | "round" | "bold"
  • gradient: { header, border, title, cell }

createProgressBar(tasks = [], options = {}) — Sync

Creates a multi-task progress bar manager.

Returns: Manager with .updateTaskProgress(name, delta)

attachFollower(base, content, options = {}) — Async

Attaches content (like badge) near an animation or after a delay.

Parameters:

• base: the animated base (must have .moving())
• content: string or function returning string
• options:
  • inline: true | false
  • inlinePosition: "left" | "right"
  • spacing: # of lines or spaces
  • delay: in milliseconds

setDefaultGradient(colors: string[]) — Sync

Sets the default gradient colors globally.

formatBytes(size, dynamicUnits = true) — Sync

Formats bytes into readable strings (e.g. 12.3 MB).

formatSeconds(seconds) — Sync

Formats seconds into hh:mm:ss format.

Terminal Components

🧩 Application UI Components

Terminal Plus now includes reusable application-style terminal components in addition to its original visual primitives.

| Component | Factory | Purpose | |---|---|---| | Paginated View | createPaginatedView() | Browse large datasets page-by-page without flooding terminal history | | Live Region | createLiveRegion() | Re-render changing content in a controlled terminal region | | Interactive List | createInteractiveList() | Keyboard-driven list navigation and selection | | Interactive Table | createInteractiveTable() | Select and navigate structured tabular data | | Searchable Selector | createSearchableSelector() | Filter and select from large collections | | Input Field | createInputField() | Reusable terminal text input | | Autocomplete | createAutocomplete() | Complete known commands, values, or paths | | Tree | createTree() | Render hierarchical data | | Breadcrumb | createBreadcrumb() | Render and navigate hierarchical paths with responsive collapsing | | Status Bar | createStatusBar() | Display connection, identity, channel, or application state | | Key Hint Bar | createKeyHintBar() | Display discoverable keyboard controls | | Tabs | createTabs() | Switch between terminal application sections | | Modal | createModal() | Present focused framed content or actions | | Command Palette | createCommandPalette() | Search and invoke commands | | Progress Group | createProgressGroup() | Track multiple concurrent operations | | Log View | createLogView() | Present structured terminal logs | | Dashboard | createDashboard() | Compose application-level terminal views | | Panel | createPanel() | Render a styled content panel | | Panel Layout | createPanelLayout() | Arrange multiple terminal panels/columns | | Form | createForm() | Collect multiple related values interactively | | Screen | createScreen() | Manage cursor movement, visibility, clearing, save, and restore | | Toast Notification | notify() | Display transient status feedback |

For components that can own keyboard input, use managed input for standalone flows and external input when the parent CLI already owns stdin or readline.

const breadcrumb = terminal.createBreadcrumb({
     inputMode : "external",
     showIndicator : true,
     showHints : true
});

console.log(
     breadcrumb.render([
          "FileNetServer",
          "Documents",
          "Projects",
          "FileTide"
     ])
);

🗂 Console Table Options

The ConsoleTable supports rich customization for column styling, layout, borders, and gradients. Below provides all the configurable options you can pass when creating a table via createTable(data, options):

| Option | Type | Description | |---------------------|--------------------|----------------------------------------------------------------------------------------------| | padding | number | Space padding inside each cell (default: 1) | | headerAlign | "left" \| "right" \| "center" | Text alignment for header cells (default: "center") | | cellAlign | "left" \| "right" \| "center" | Text alignment for regular cells (default: "left") | | borderStyle | "solid" \| "double" \| "round" \| "bold" | Style of table border characters (default: "solid") | | headerColor | function | Function to apply color/styling to header cell content | | borderColor | function | Function to apply color/styling to border characters | | cellColor | function(content, column, row) | Function to apply color/styling per cell content (default: returns raw content) | | columnOrder | string[] | Define explicit column order instead of automatic detection | | columnNames | object | Map of originalKey : displayLabel to rename column headers | | title | string | Optional table title (rendered above the table) | | tableNumber | number | Optional number to tag the table for reference | | gradient.title | [string, string] | Gradient color pair applied to the title (overrides static color) | | gradient.header | [string, string] | Gradient color pair applied to header text | | gradient.border | [string, string] | Gradient color pair applied to border characters | | gradient.cell | [string, string] | Gradient color pair applied to cell content |

🏷 Terminal Badge Options

The TerminalBadge component enables you to display beautifully styled label badges directly in the terminal with support for colors, gradients, icons, and format types.

You can use it via:

terminal.printBadge("Build Success", options);
const badge = terminal.getBadge("MyCLI", options);

| Option | Type | Description | |---------------------|----------------------|----------------------------------------------------------------------------------------------| | icon | string | Emoji or icon to prepend inside the badge (e.g., "🚀") | | padding | number | Number of spaces on both sides of the content (default: 1) | | backgroundColor | string (hex) | Background color of the badge (default: "#6c63ff") | | textColor | string (hex) | Foreground (text) color inside the badge (default: "#ffffff") | | gradient | [string, string] | Optional gradient colors to override backgroundColor | | type | "sleek" \| "sci-fi" \| "rounded" \| "classic" | Defines the badge frame style (default: "sleek") | | inline | boolean | Whether to render the badge inline or on its own line (default: true) |

📊 Console Progress Bar Options

The ConsoleProgressBarManager allows you to manage multiple terminal-based progress bars with advanced customization. You can create a manager using:

const barManager = terminal.createProgressBar(tasks, options);

Tasks Format

An object with at least:

{ name : "Upload", size : 1000 }

🛠 Options

| Option | Type | Description | |----------------------|-----------------------|-----------------------------------------------------------------------------------------------| | barWidth | number | Total width of the progress bar (default: 40) | | barChar | string | Character used to fill the progress bar (default: "█") | | emptyChar | string | Character used for the unfilled portion (default: "░") | | showPercentage | boolean | Show percentage next to the bar (default: true) | | showCount | boolean | Show current / total progress numbers (default: true) | | showBarBorder | boolean | Surround the bar with borders (default: false) | | barBorderChar | [string, string] | Custom left and right characters for the border (default: ["[", "]"]) | | labelAlign | "left" \| "center" \| "right" | Alignment of the task label (default: "left") | | barGradient | [string, string] | Gradient colors used inside the filled bar section | | textColor | string | Hex color applied to label and percentage (default: "#ffffff") | | completedIcon | string | Optional icon to show when a task reaches 100% (e.g., "✅") | | autoRender | boolean | If true, automatically calls displayPage() and listenForInput() (default: true) |

🔧 Task Methods

After creating the bar manager, you can control tasks with:

barManager.updateTaskProgress(taskName, amount);
barManager.completeTask(taskName);
barManager.completeAll();

Example

const tasks = [
     { name : "Upload", size : 1000 },
     { name : "Process", size : 500 }
];

const barManager = terminal.createProgressBar(tasks, {
     barWidth : 30,
     barChar : "#",
     emptyChar : "-",
     barGradient : ["#00C9FF", "#92FE9D"],
     completedIcon : "✅"
});

// Simulate updates
barManager.updateTaskProgress("Upload", 100);

💡 Console Progress Bar uses cumulative progression — keep calling updateTaskProgress to move it forward.

🔄 Terminal Spinner Options

The TerminalSpinner creates beautiful animated loaders with support for color gradients, shifting, icons, and custom frames.

You can start a spinner using:

const spinner = terminal.createSpinner("Loading...", options);
spinner.start();

// Optional: stop after done
setTimeout(() => spinner.stop("✅ Done!"), 3000);

🛠 Options

| Option | Type | Description | |--------------------------|--------------------------|-----------------------------------------------------------------------------------------------| | preset | string | Built-in spinner style (e.g., "dots", "rocket", etc.) | | frames | string[] | Custom array of frame strings (overrides preset if provided) | | interval | number | Milliseconds between each frame (default: 80) | | textColor | string \| string[] | Text color or gradient colors array | | backgroundColor | string \| string[] | Background color or gradient colors array | | icon | string | Emoji or icon prepended to the spinner label (e.g., "🚀") | | prefix | string | String to show before the spinner block | | suffix | string | String to show after the spinner block | | padding | number | Number of spaces around the spinner text (default: 1) | | inline | boolean | Whether to print on the same line (true) or as a new line per frame (false) | | gradientShift | boolean | Enable live shifting of text/background gradients per frame | | textGradientSpeed | number | Number of frames before shifting text gradient (default: 1) | | bgGradientSpeed | number | Number of frames before shifting background gradient (default: 1) | | textGradientReverse | boolean | Reverse the direction of text gradient shift | | bgGradientReverse | boolean | Reverse the direction of background gradient shift |

🎞️ Built-in Spinner Presets

| Preset | Description | |--------------|---------------------------------| | dots | Classic braille spinner | | line | Rotating slashes | | arrows | Directional arrow cycle | | circle | Circular quadrant spinner | | bounce | Bouncing dot loader | | bar | Progress bar simulation | | grow | Vertical growth bar | | clock | Analog clock face rotation | | simple | Expanding ellipsis | | supercape | Superhero flying dash | | fireball | Flame swipe with momentum | | magic | Glowing spell swirl | | rocket | Rocket launch animation | | retro | Alien + UFO loop |

🧪 Component Demos

Interactive components are easiest to test independently. Terminal Plus uses focused start-terminal-* scripts so one component does not take over terminal input before another demo runs.

npm run start-terminal
npm run start-terminal-pagination
npm run start-terminal-tabs
npm run start-terminal-breadcrumb
npm run start-terminal-form
npm run start-terminal-screen
npm run start-terminal-searchable-selector
npm run start-terminal-progress-group

Additional component demos can follow the same convention:

start-terminal-<component>

📦 Install

npm install @trap_stevo/terminal-plus

🚀 Example Usage

Here’s a full example of how to use TerminalPlus to build a legendarily appealing terminal output:

const TerminalPlus = require("@trap_stevo/terminal-plus");

const terminal = new TerminalPlus({
     gradientSpeed : 75,
     defaultGradient : ["#FF00FF", "#00FFFF"]
});

// 🔹 Gradient Text
terminal.printGradient("✨ Welcome to LegendaryTerminal ✨");

// 🔹 Moving Gradient (animated)
const badge = terminal.getBadge("MyCLI", {
     icon : "🚀",
     backgroundColor : "#007BFF",
     textColor : "#ffffff",
     padding : 2,
     rounded : true
});

const anim = terminal.printMovingGradient("✨ Animating with style...", ["#FF6B6B", "#FFD93D"]);
anim.setFollower(badge);

setTimeout(() => {
     anim.stop();
     console.log("\n✅ Animation done.\n");
}, 3000);

// 🔹 Terminal Badge
terminal.printBadge("MyCLI", {
     icon : "🚀",
     backgroundColor : "#007BFF",
     textColor : "#ffffff",
     padding : 2,
     rounded : true
});

// 🔹 Custom Styled Badge with Gradient
terminal.printBadge("Build Success", {
     icon : "✅",
     gradient : ["#28a745", "#85e085"],
     textColor : "#000000",
     padding : 1,
     rounded : true
});

// 🔹 Console Table
const tableOutput = terminal.createTable([
     { name : "Alice", role : "Admin", age : 30 },
     { name : "Bob", role : "User", age : 25 }
], {
     columnNames : { name : "Name", role : "Role", age : "Age" },
     gradient : {
          header : ["#00C9FF", "#92FE9D"],
          cell : ["#FFDEE9", "#B5FFFC"]
     },
     borderStyle : "round"
});

console.log("\n" + tableOutput);

// 🔹 Styled Text Using applyColor
const styled = terminal.printColor("🛡 SECURE", {
     backgroundColor : "#222831",
     textColor : "#00FFF5"
});

process.stdout.write(styled);

// 🔹 Inline Badge Follower
terminal.attachFollower(styled, badge, { inline : true });

// 🔹 Byte & Time Format Utilities
console.log("\nFile size:", terminal.formatBytes(12582912));
console.log("Estimated time:", terminal.formatSeconds(9876));

setTimeout(() => {
          const spinner = terminal.createSpinner("Launching to the stars...", {
               preset : "rocket",
               textColor : ["#00FFF5", "#1A73E8", "#9D00FF"],
               backgroundColor : ["#0F1117", "#11131A", "#0F1117"],
               gradientShift : true,
               textGradientSpeed : 0.1,
               bgGradientSpeed : 2,
               textGradientReverse : false,
               bgGradientReverse : true,
               interval : 100
          });
          
          setTimeout(() =>  {
               spinner.stop("🚀 We have liftoff!");
          }, 4000);
}, 3000);

🧠 Customize every visual element, combine components, and inject dynamic elegance into every CLI interaction.

📜 License

SCL-1.0-Universal

🧙 Terminal Magic. Command Layer Power.

Turn everyday terminal output into a high-impact visual experience.
Use it to elevate your CLI tools, installation wizards, developer scripts, or deployment logs with elegance and clarity.

Let your terminal shine with color, clarity, and control.