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
```