or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

buffers-graphics.mdcolors-styling.mddocument-model.mdindex.mdinteractive-input.mdterminal-control.md
tile.json

tessl/npm-terminal-kit

Comprehensive Node.js terminal library with 256 colors, interactive components, and advanced graphics capabilities

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/terminal-kit@3.1.x

To install, run

npx @tessl/cli install tessl/npm-terminal-kit@3.1.0

index.mddocs/

Terminal Kit

Terminal Kit is a comprehensive Node.js library for creating rich terminal applications with advanced features including 256/24-bit color support, keyboard and mouse input handling, interactive UI components, screen and text buffers with 32-bit RGBA composition, image loading and rendering capabilities, and extensive styling options. It provides both low-level terminal control functions and high-level components for building complex command-line interfaces.

Package Information

  • Package Name: terminal-kit
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install terminal-kit

Core Imports

const termkit = require('terminal-kit');
const terminal = termkit.terminal;

For specific components:

const { Terminal, ScreenBuffer, TextBuffer } = require('terminal-kit');

Basic Usage

const term = require('terminal-kit').terminal;

// Simple colored output with chaining
term.red('Hello ').green('colorful ').cyan('world!\n');

// Interactive input
term.magenta('What is your name? ').bold.cyan();
term.inputField({ history: ['John', 'Jane'] }, (error, input) => {
  term.green('\nHello %s!\n', input);
  process.exit();
});

Architecture

Terminal Kit is built around several key architectural components:

  • Terminal Class: Core terminal control with chainable methods for styling, colors, and positioning
  • Document Model: High-level UI framework with components like buttons, menus, forms, and layout containers
  • Buffer System: Advanced display management with ScreenBuffer and TextBuffer for complex graphics
  • Input Handling: Comprehensive keyboard and mouse event processing with customizable handlers
  • Color System: Full spectrum color support from basic ANSI to 24-bit RGB with color conversion utilities
  • Terminal Detection: Automatic terminal capability detection and optimization

Capabilities

Terminal Control and Cursor Management

Core terminal control functionality including cursor positioning, screen manipulation, scrolling, and display area management.

// Main terminal instance
const terminal: Terminal;

// Cursor positioning
terminal.moveTo(x: number, y: number): Terminal;
terminal.move(x: number, y: number): Terminal;
terminal.up(n?: number): Terminal;
terminal.down(n?: number): Terminal;
terminal.left(n?: number): Terminal;
terminal.right(n?: number): Terminal;

// Screen control
terminal.clear(): Terminal;
terminal.eraseDisplayBelow(): Terminal;
terminal.eraseDisplayAbove(): Terminal;
terminal.scrollUp(n?: number): Terminal;
terminal.scrollDown(n?: number): Terminal;

Terminal Control

Colors and Styling

Comprehensive color and text styling system supporting ANSI colors, 256-color palette, RGB colors, and text formatting.

// Basic colors (chainable)
terminal.red(text?: string): Terminal;
terminal.green(text?: string): Terminal;
terminal.blue(text?: string): Terminal;

// Advanced colors
terminal.color256(colorIndex: number, text?: string): Terminal;
terminal.colorRgb(r: number, g: number, b: number, text?: string): Terminal;

// Text styling
terminal.bold(state?: boolean): Terminal;
terminal.italic(state?: boolean): Terminal;
terminal.underline(state?: boolean): Terminal;

Colors and Styling

Interactive Input Components

User input handling including text fields, menus, file selection, and interactive prompts with full keyboard and mouse support.

// Text input
terminal.inputField(options: InputFieldOptions, callback: (error: Error | null, input: string) => void): void;

// Menu systems
terminal.singleColumnMenu(items: string[], options: MenuOptions, callback: MenuCallback): void;
terminal.gridMenu(items: string[], options: GridMenuOptions, callback: MenuCallback): void;

// File operations  
terminal.fileInput(options: FileInputOptions, callback: FileInputCallback): void;

interface InputFieldOptions {
  history?: string[];
  autoComplete?: string[] | Function;
  default?: string;
  // ... additional options
}

Interactive Input

Document Model UI Framework

High-level declarative UI framework with components for building complex terminal applications including forms, layouts, and interactive elements.

// Document creation
const Document: typeof import('./document/Document');
const document: Document;

// UI Components
const Button: typeof import('./document/Button');
const TextBox: typeof import('./document/TextBox');
const Form: typeof import('./document/Form');
const Layout: typeof import('./document/Layout');

// Component instantiation
new Button(options: ButtonOptions): Button;
new TextBox(options: TextBoxOptions): TextBox;
new Form(options: FormOptions): Form;

Document Model

Screen Buffers and Advanced Graphics

Advanced display management with screen buffers, text buffers, image rendering, and 32-bit RGBA composition for complex graphics.

// Buffer classes
const ScreenBuffer: typeof import('./ScreenBuffer');
const ScreenBufferHD: typeof import('./ScreenBufferHD');  
const TextBuffer: typeof import('./TextBuffer');

// Buffer creation
new ScreenBuffer(options: ScreenBufferOptions): ScreenBuffer;
new TextBuffer(options: TextBufferOptions): TextBuffer;

// Image operations  
terminal.drawImage(url: string, options: ImageOptions, callback: ImageCallback): void;

interface ScreenBufferOptions {
  dst: Terminal;
  width?: number;
  height?: number;
  // ... additional options
}

Buffers and Graphics

Global Configuration

// Global configuration object
termkit.globalConfig: {
  preferProcessSigwinch?: boolean;
};

// Terminal detection
termkit.guessTerminal(force?: boolean): TerminalInfo;
termkit.Terminal: typeof Terminal;
termkit.createTerminal: (options: TerminalCreateOptions) => Terminal;

interface TerminalInfo {
  generic?: string;
  appId?: string;
  appName?: string;
  isTTY: boolean;
  isSSH: boolean;
  safe: boolean;
}

interface TerminalCreateOptions {
  stdin?: NodeJS.ReadStream;
  stdout?: NodeJS.WriteStream;
  stderr?: NodeJS.WriteStream;
  generic?: string;
  appId?: string;
  isTTY?: boolean;
  isSSH?: boolean;
  processSigwinch?: boolean;
  preferProcessSigwinch?: boolean;
}

Utility Functions

// Color utilities (from misc.js)
termkit.colorNameToIndex(colorName: string): number;
termkit.indexToColorName(colorIndex: number): string;
termkit.colorNameToRgb(colorName: string): { r: number; g: number; b: number };
termkit.rgbToColorName(r: number, g: number, b: number): string;
termkit.color256ToRgb(colorIndex: number): { r: number; g: number; b: number };
termkit.rgbToColor256(r: number, g: number, b: number): number;
termkit.hexToRgba(hex: string): { r: number; g: number; b: number; a: number };
termkit.rgbToHex(r: number, g: number, b: number): string;

// Deprecated aliases (for backwards compatibility)
termkit.color2index(colorName: string): number;
termkit.index2color(colorIndex: number): string;
termkit.hexToColor(hex: string): { r: number; g: number; b: number; a: number };

// Auto-completion
termkit.autoComplete(inputString: string, possibilities: string[], returnAlternatives?: boolean): string | string[];

// TTY utilities
termkit.tty.getPath(): string;
termkit.tty.getInput(): NodeJS.ReadStream;
termkit.tty.getOutput(): NodeJS.WriteStream;

Specialized Components

// Virtual Terminal Emulator
termkit.Vte: typeof import('./vte/Vte');

// Special characters and animations
termkit.spChars: {
  animation: {
    asciiSpinner: string[];
    lineSpinner: string[];
    dotSpinner: string[];
    // ... other animation sequences
  };
  // ... other special character collections
};

// Color palette management
termkit.Palette: typeof import('./Palette');

// Rectangle utilities
termkit.Rect: typeof import('./Rect');

External Dependencies

// Available external libraries
termkit.chroma: typeof import('chroma-js');