0
# Terminal Kit
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: terminal-kit
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install terminal-kit`
10
11
## Core Imports
12
13
```javascript
14
const termkit = require('terminal-kit');
15
const terminal = termkit.terminal;
16
```
17
18
For specific components:
19
20
```javascript
21
const { Terminal, ScreenBuffer, TextBuffer } = require('terminal-kit');
22
```
23
24
## Basic Usage
25
26
```javascript
27
const term = require('terminal-kit').terminal;
28
29
// Simple colored output with chaining
30
term.red('Hello ').green('colorful ').cyan('world!\n');
31
32
// Interactive input
33
term.magenta('What is your name? ').bold.cyan();
34
term.inputField({ history: ['John', 'Jane'] }, (error, input) => {
35
term.green('\nHello %s!\n', input);
36
process.exit();
37
});
38
```
39
40
## Architecture
41
42
Terminal Kit is built around several key architectural components:
43
44
- **Terminal Class**: Core terminal control with chainable methods for styling, colors, and positioning
45
- **Document Model**: High-level UI framework with components like buttons, menus, forms, and layout containers
46
- **Buffer System**: Advanced display management with ScreenBuffer and TextBuffer for complex graphics
47
- **Input Handling**: Comprehensive keyboard and mouse event processing with customizable handlers
48
- **Color System**: Full spectrum color support from basic ANSI to 24-bit RGB with color conversion utilities
49
- **Terminal Detection**: Automatic terminal capability detection and optimization
50
51
## Capabilities
52
53
### Terminal Control and Cursor Management
54
55
Core terminal control functionality including cursor positioning, screen manipulation, scrolling, and display area management.
56
57
```javascript { .api }
58
// Main terminal instance
59
const terminal: Terminal;
60
61
// Cursor positioning
62
terminal.moveTo(x: number, y: number): Terminal;
63
terminal.move(x: number, y: number): Terminal;
64
terminal.up(n?: number): Terminal;
65
terminal.down(n?: number): Terminal;
66
terminal.left(n?: number): Terminal;
67
terminal.right(n?: number): Terminal;
68
69
// Screen control
70
terminal.clear(): Terminal;
71
terminal.eraseDisplayBelow(): Terminal;
72
terminal.eraseDisplayAbove(): Terminal;
73
terminal.scrollUp(n?: number): Terminal;
74
terminal.scrollDown(n?: number): Terminal;
75
```
76
77
[Terminal Control](./terminal-control.md)
78
79
### Colors and Styling
80
81
Comprehensive color and text styling system supporting ANSI colors, 256-color palette, RGB colors, and text formatting.
82
83
```javascript { .api }
84
// Basic colors (chainable)
85
terminal.red(text?: string): Terminal;
86
terminal.green(text?: string): Terminal;
87
terminal.blue(text?: string): Terminal;
88
89
// Advanced colors
90
terminal.color256(colorIndex: number, text?: string): Terminal;
91
terminal.colorRgb(r: number, g: number, b: number, text?: string): Terminal;
92
93
// Text styling
94
terminal.bold(state?: boolean): Terminal;
95
terminal.italic(state?: boolean): Terminal;
96
terminal.underline(state?: boolean): Terminal;
97
```
98
99
[Colors and Styling](./colors-styling.md)
100
101
### Interactive Input Components
102
103
User input handling including text fields, menus, file selection, and interactive prompts with full keyboard and mouse support.
104
105
```javascript { .api }
106
// Text input
107
terminal.inputField(options: InputFieldOptions, callback: (error: Error | null, input: string) => void): void;
108
109
// Menu systems
110
terminal.singleColumnMenu(items: string[], options: MenuOptions, callback: MenuCallback): void;
111
terminal.gridMenu(items: string[], options: GridMenuOptions, callback: MenuCallback): void;
112
113
// File operations
114
terminal.fileInput(options: FileInputOptions, callback: FileInputCallback): void;
115
116
interface InputFieldOptions {
117
history?: string[];
118
autoComplete?: string[] | Function;
119
default?: string;
120
// ... additional options
121
}
122
```
123
124
[Interactive Input](./interactive-input.md)
125
126
### Document Model UI Framework
127
128
High-level declarative UI framework with components for building complex terminal applications including forms, layouts, and interactive elements.
129
130
```javascript { .api }
131
// Document creation
132
const Document: typeof import('./document/Document');
133
const document: Document;
134
135
// UI Components
136
const Button: typeof import('./document/Button');
137
const TextBox: typeof import('./document/TextBox');
138
const Form: typeof import('./document/Form');
139
const Layout: typeof import('./document/Layout');
140
141
// Component instantiation
142
new Button(options: ButtonOptions): Button;
143
new TextBox(options: TextBoxOptions): TextBox;
144
new Form(options: FormOptions): Form;
145
```
146
147
[Document Model](./document-model.md)
148
149
### Screen Buffers and Advanced Graphics
150
151
Advanced display management with screen buffers, text buffers, image rendering, and 32-bit RGBA composition for complex graphics.
152
153
```javascript { .api }
154
// Buffer classes
155
const ScreenBuffer: typeof import('./ScreenBuffer');
156
const ScreenBufferHD: typeof import('./ScreenBufferHD');
157
const TextBuffer: typeof import('./TextBuffer');
158
159
// Buffer creation
160
new ScreenBuffer(options: ScreenBufferOptions): ScreenBuffer;
161
new TextBuffer(options: TextBufferOptions): TextBuffer;
162
163
// Image operations
164
terminal.drawImage(url: string, options: ImageOptions, callback: ImageCallback): void;
165
166
interface ScreenBufferOptions {
167
dst: Terminal;
168
width?: number;
169
height?: number;
170
// ... additional options
171
}
172
```
173
174
[Buffers and Graphics](./buffers-graphics.md)
175
176
## Global Configuration
177
178
```javascript { .api }
179
// Global configuration object
180
termkit.globalConfig: {
181
preferProcessSigwinch?: boolean;
182
};
183
184
// Terminal detection
185
termkit.guessTerminal(force?: boolean): TerminalInfo;
186
termkit.Terminal: typeof Terminal;
187
termkit.createTerminal: (options: TerminalCreateOptions) => Terminal;
188
189
interface TerminalInfo {
190
generic?: string;
191
appId?: string;
192
appName?: string;
193
isTTY: boolean;
194
isSSH: boolean;
195
safe: boolean;
196
}
197
198
interface TerminalCreateOptions {
199
stdin?: NodeJS.ReadStream;
200
stdout?: NodeJS.WriteStream;
201
stderr?: NodeJS.WriteStream;
202
generic?: string;
203
appId?: string;
204
isTTY?: boolean;
205
isSSH?: boolean;
206
processSigwinch?: boolean;
207
preferProcessSigwinch?: boolean;
208
}
209
```
210
211
## Utility Functions
212
213
```javascript { .api }
214
// Color utilities (from misc.js)
215
termkit.colorNameToIndex(colorName: string): number;
216
termkit.indexToColorName(colorIndex: number): string;
217
termkit.colorNameToRgb(colorName: string): { r: number; g: number; b: number };
218
termkit.rgbToColorName(r: number, g: number, b: number): string;
219
termkit.color256ToRgb(colorIndex: number): { r: number; g: number; b: number };
220
termkit.rgbToColor256(r: number, g: number, b: number): number;
221
termkit.hexToRgba(hex: string): { r: number; g: number; b: number; a: number };
222
termkit.rgbToHex(r: number, g: number, b: number): string;
223
224
// Deprecated aliases (for backwards compatibility)
225
termkit.color2index(colorName: string): number;
226
termkit.index2color(colorIndex: number): string;
227
termkit.hexToColor(hex: string): { r: number; g: number; b: number; a: number };
228
229
// Auto-completion
230
termkit.autoComplete(inputString: string, possibilities: string[], returnAlternatives?: boolean): string | string[];
231
232
// TTY utilities
233
termkit.tty.getPath(): string;
234
termkit.tty.getInput(): NodeJS.ReadStream;
235
termkit.tty.getOutput(): NodeJS.WriteStream;
236
```
237
238
## Specialized Components
239
240
```javascript { .api }
241
// Virtual Terminal Emulator
242
termkit.Vte: typeof import('./vte/Vte');
243
244
// Special characters and animations
245
termkit.spChars: {
246
animation: {
247
asciiSpinner: string[];
248
lineSpinner: string[];
249
dotSpinner: string[];
250
// ... other animation sequences
251
};
252
// ... other special character collections
253
};
254
255
// Color palette management
256
termkit.Palette: typeof import('./Palette');
257
258
// Rectangle utilities
259
termkit.Rect: typeof import('./Rect');
260
```
261
262
## External Dependencies
263
264
```javascript { .api }
265
// Available external libraries
266
termkit.chroma: typeof import('chroma-js');
267
```