0
# Interactive Input
1

2
Terminal Kit provides comprehensive input capabilities including text fields, menus, file selection, and interactive prompts with full keyboard and mouse support.
3

4
## Text Input
5

6
### Input Field
7

8
```javascript { .api }
9
terminal.inputField(options: InputFieldOptions, callback: (error: Error | null, input: string) => void): void;
10
```
11

12
Create an interactive text input field with history, auto-completion, and validation.
13

14
```javascript { .api }
15
interface InputFieldOptions {
16
  history?: string[];
17
  autoComplete?: string[] | Function;
18
  autoCompleteMenu?: boolean;
19
  autoCompleteHint?: boolean;
20
  default?: string;
21
  placeholder?: string;
22
  maxLength?: number;
23
  minLength?: number;
24
  echo?: boolean;
25
  echoChar?: string;
26
  cancelable?: boolean;
27
  style?: object;
28
  hintStyle?: object;
29
  maxAutocomplete?: number;
30
  keyBindings?: object;
31
  tokenHook?: Function;
32
  tokenResetHook?: Function;
33
  tokenRegExp?: RegExp;
34
}
35
```
36

37
```javascript
38
const term = require('terminal-kit').terminal;
39

40
// Basic input field
41
term.cyan('Enter your name: ');
42
term.inputField((error, input) => {
43
  term.green('\nHello %s!\n', input);
44
});
45

46
// Advanced input with history and auto-completion
47
const cities = ['New York', 'Los Angeles', 'Chicago', 'Houston', 'Phoenix'];
48
term.magenta('Enter a city: ');
49
term.inputField({
50
  history: ['New York', 'San Francisco'],
51
  autoComplete: cities,
52
  autoCompleteMenu: true,
53
  maxLength: 50
54
}, (error, input) => {
55
  term.green('\nYou selected: %s\n', input);
56
});
57
```
58

59
### Yes/No Prompts
60

61
```javascript { .api }
62
terminal.yesOrNo(options: YesOrNoOptions, callback: (error: Error | null, result: boolean) => void): void;
63
```
64

65
Create yes/no confirmation prompts.
66

67
```javascript { .api }
68
interface YesOrNoOptions {
69
  yes?: string[];
70
  no?: string[];
71
  echoYes?: string;
72
  echoNo?: string;
73
  default?: boolean;
74
}
75
```
76

77
```javascript
78
term.cyan('Do you want to continue? [Y/n] ');
79
term.yesOrNo({ yes: ['y', 'Y'], no: ['n', 'N'] }, (error, result) => {
80
  if (result) {
81
    term.green('\nContinuing...\n');
82
  } else {
83
    term.red('\nAborted.\n');
84
  }
85
});
86
```
87

88
## File Operations
89

90
### File Input
91

92
```javascript { .api }
93
terminal.fileInput(options: FileInputOptions, callback: (error: Error | null, input: string) => void): void;
94
```
95

96
Interactive file/directory selection with tab completion.
97

98
```javascript { .api }
99
interface FileInputOptions {
100
  baseDir?: string;
101
  autoComplete?: boolean;
102
  default?: string;
103
  cancelable?: boolean;
104
  style?: object;
105
}
106
```
107

108
```javascript
109
term.cyan('Select a file: ');
110
term.fileInput({ baseDir: process.cwd() }, (error, input) => {
111
  if (input) {
112
    term.green('\nSelected file: %s\n', input);
113
  }
114
});
115
```
116

117
## Menu Systems
118

119
### Single Line Menu
120

121
```javascript { .api }
122
terminal.singleLineMenu(items: string[], options: SingleLineMenuOptions, callback: (error: Error | null, response: MenuResponse) => void): void;
123
```
124

125
Horizontal menu selection.
126

127
```javascript { .api }
128
interface SingleLineMenuOptions {
129
  y?: number;
130
  separator?: string;
131
  nextPageHint?: string;
132
  previousPageHint?: string;
133
  style?: object;
134
  selectedStyle?: object;
135
  submittedStyle?: object;
136
  leftPadding?: string;
137
  rightPadding?: string;
138
  keyBindings?: object;
139
  cancelable?: boolean;
140
  exitOnUnexpectedKey?: boolean;
141
}
142

143
interface MenuResponse {
144
  selectedIndex: number;
145
  selectedText: string;
146
  x: number;
147
  y: number;
148
  canceled: boolean;
149
  unexpectedKey?: string;
150
}
151
```
152

153
```javascript
154
const options = ['New', 'Open', 'Save', 'Exit'];
155
term.singleLineMenu(options, (error, response) => {
156
  term('\nYou selected: %s\n', response.selectedText);
157
});
158
```
159

160
### Single Column Menu
161

162
```javascript { .api }
163
terminal.singleColumnMenu(items: string[], options: SingleColumnMenuOptions, callback: (error: Error | null, response: MenuResponse) => void): void;
164
```
165

166
Vertical menu selection.
167

168
```javascript { .api }
169
interface SingleColumnMenuOptions {
170
  y?: number;
171
  style?: object;
172
  selectedStyle?: object;
173
  submittedStyle?: object;
174
  leftPadding?: string;
175
  selectedLeftPadding?: string;
176
  rightPadding?: string;
177
  selectedRightPadding?: string;
178
  itemMaxWidth?: number;
179
  keyBindings?: object;
180
  cancelable?: boolean;
181
  exitOnUnexpectedKey?: boolean;
182
  continueOnSubmit?: boolean;
183
  selectedIndex?: number;
184
}
185
```
186

187
```javascript
188
const menuItems = [
189
  'Create new project',
190
  'Open existing project', 
191
  'Recent projects',
192
  'Settings',
193
  'Exit'
194
];
195

196
term.singleColumnMenu(menuItems, {
197
  selectedStyle: term.inverse
198
}, (error, response) => {
199
  term('\nSelected: %s (index: %d)\n', response.selectedText, response.selectedIndex);
200
});
201
```
202

203
### Grid Menu
204

205
```javascript { .api }
206
terminal.gridMenu(items: string[], options: GridMenuOptions, callback: (error: Error | null, response: MenuResponse) => void): void;
207
```
208

209
Grid-based menu layout for multiple columns.
210

211
```javascript { .api }
212
interface GridMenuOptions {
213
  width?: number;
214
  x?: number;
215
  y?: number;
216
  leftPadding?: string;
217
  rightPadding?: string;
218
  itemMaxWidth?: number;
219
  keyBindings?: object;
220
  cancelable?: boolean;
221
  exitOnUnexpectedKey?: boolean;
222
  style?: object;
223
  selectedStyle?: object;
224
  submittedStyle?: object;
225
}
226
```
227

228
```javascript
229
const colors = [
230
  'red', 'green', 'blue', 'yellow',
231
  'cyan', 'magenta', 'white', 'black',
232
  'brightRed', 'brightGreen', 'brightBlue', 'brightYellow'
233
];
234

235
term.gridMenu(colors, {
236
  width: 4,
237
  selectedStyle: term.inverse
238
}, (error, response) => {
239
  term('\nSelected color: %s\n', response.selectedText);
240
});
241
```
242

243
## Progress Indicators
244

245
### Progress Bar
246

247
```javascript { .api }
248
terminal.progressBar(options: ProgressBarOptions): ProgressBarController;
249
```
250

251
Create animated progress bars.
252

253
```javascript { .api }
254
interface ProgressBarOptions {
255
  width?: number;
256
  percent?: boolean;
257
  eta?: boolean;
258
  items?: boolean;
259
  title?: string;
260
  barStyle?: object;
261
  barBracketStyle?: object;
262
  percentStyle?: object;
263
  etaStyle?: object;
264
  itemStyle?: object;
265
  titleStyle?: object;
266
  itemSize?: number;
267
  barChar?: string;
268
  barHeadChar?: string;
269
  maxRefreshTime?: number;
270
  minRefreshTime?: number;
271
  inline?: boolean;
272
  syncMode?: boolean;
273
}
274

275
interface ProgressBarController {
276
  update(updateObject: ProgressBarUpdate): void;
277
  startItem(name: string): void;
278
  itemDone(name: string): void;
279
  stop(): void;
280
}
281

282
interface ProgressBarUpdate {
283
  progress?: number;
284
  title?: string;
285
  eta?: number;
286
  item?: string;
287
}
288
```
289

290
```javascript
291
const progressBar = term.progressBar({
292
  width: 80,
293
  title: 'Downloading files...',
294
  eta: true,
295
  percent: true
296
});
297

298
let progress = 0;
299
const timer = setInterval(() => {
300
  progress += 0.1;
301
  progressBar.update({ progress });
302
  
303
  if (progress >= 1) {
304
    clearInterval(timer);
305
    progressBar.stop();
306
    term('\nDownload complete!\n');
307
  }
308
}, 100);
309
```
310

311
### Slow Typing Animation
312

313
```javascript { .api }
314
terminal.slowTyping(text: string, options: SlowTypingOptions, callback?: () => void): void;
315
```
316

317
Animate text typing effect.
318

319
```javascript { .api }
320
interface SlowTypingOptions {
321
  style?: object;
322
  delay?: number;
323
  flashStyle?: object;
324
  flashDelay?: number;
325
}
326
```
327

328
```javascript
329
term.slowTyping('Hello, this text will appear slowly...', {
330
  delay: 100,
331
  flashStyle: term.brightWhite
332
}, () => {
333
  term('\nAnimation complete!\n');
334
});
335
```
336

337
### Spinner Animation
338

339
```javascript { .api }
340
terminal.spinner(options: SpinnerOptions): AnimatedText;
341
```
342

343
Create animated spinners for loading indicators.
344

345
```javascript { .api }
346
interface SpinnerOptions {
347
  animation?: string;
348
  x?: number;
349
  y?: number;
350
  style?: object;
351
}
352
```
353

354
```javascript
355
// Simple line spinner
356
const spinner = term.spinner();
357

358
// Specific animation type
359
const colorSpinner = term.spinner('unboxing-color');
360

361
// Custom positioned spinner
362
const positionedSpinner = term.spinner({
363
  animation: 'dotSpinner',
364
  x: 10,
365
  y: 5,
366
  style: { color: 'cyan' }
367
});
368

369
// Control spinner
370
setTimeout(() => spinner.animate(false), 3000); // Stop after 3 seconds
371
```
372

373
## Event Handling
374

375
### Keyboard Events
376

377
Terminal Kit provides comprehensive keyboard event handling when input is grabbed.
378

379
```javascript { .api }
380
terminal.grabInput(options?: GrabInputOptions): void;
381

382
interface GrabInputOptions {
383
  mouse?: boolean | string;
384
  focus?: boolean;
385
}
386
```
387

388
```javascript
389
term.grabInput({ mouse: 'button' });
390

391
term.on('key', (name, matches, data) => {
392
  term('Key pressed: %s\n', name);
393
  
394
  // Handle specific keys
395
  switch (name) {
396
    case 'CTRL_C':
397
      term.releaseInput();
398
      process.exit();
399
      break;
400
    case 'ENTER':
401
      term.green('Enter pressed!\n');
402
      break;
403
    case 'UP':
404
      term.up(1);
405
      break;
406
    case 'DOWN':
407
      term.down(1);
408
      break;
409
  }
410
});
411
```
412

413
### Mouse Events
414

415
```javascript
416
term.grabInput({ mouse: 'button' });
417

418
term.on('mouse', (name, data) => {
419
  switch (name) {
420
    case 'MOUSE_LEFT_BUTTON_PRESSED':
421
      term.moveTo(data.x, data.y).red('●');
422
      break;
423
    case 'MOUSE_RIGHT_BUTTON_PRESSED':
424
      term.moveTo(data.x, data.y).blue('●');
425
      break;
426
    case 'MOUSE_WHEEL_UP':
427
      term.scrollUp(3);
428
      break;
429
    case 'MOUSE_WHEEL_DOWN':
430
      term.scrollDown(3);
431
      break;
432
  }
433
});
434
```
435

436
## Auto-completion
437

438
### Custom Auto-completion
439

440
```javascript { .api }
441
autoComplete(inputString: string, possibilities: string[], returnAlternatives?: boolean): string | string[];
442
```
443

444
Standalone auto-completion function.
445

446
```javascript
447
const termkit = require('terminal-kit');
448

449
const commands = ['help', 'exit', 'clear', 'history', 'settings'];
450
const input = 'he';
451
const completion = termkit.autoComplete(input, commands);
452

453
console.log(completion); // 'help'
454

455
// Get all alternatives
456
const alternatives = termkit.autoComplete(input, commands, true);
457
console.log(alternatives); // ['help']
458
```
459

460
## Usage Examples
461

462
### Interactive CLI Application
463

464
```javascript
465
const term = require('terminal-kit').terminal;
466

467
function showMainMenu() {
468
  term.clear();
469
  term.magenta.bold('=== CLI Application ===\n\n');
470
  
471
  const options = [
472
    'Create new item',
473
    'List items',
474
    'Search items',
475
    'Settings',
476
    'Exit'
477
  ];
478
  
479
  term.singleColumnMenu(options, (error, response) => {
480
    term('\n');
481
    
482
    switch (response.selectedIndex) {
483
      case 0:
484
        createItem();
485
        break;
486
      case 1:
487
        listItems();
488
        break;
489
      case 2:
490
        searchItems();
491
        break;
492
      case 3:
493
        showSettings();
494
        break;
495
      case 4:
496
        term.red('Goodbye!\n');
497
        process.exit();
498
        break;
499
    }
500
  });
501
}
502

503
function createItem() {
504
  term.cyan('Enter item name: ');
505
  term.inputField((error, input) => {
506
    if (input) {
507
      term.green('\nCreated item: %s\n', input);
508
    }
509
    
510
    term.cyan('\nPress any key to continue...');
511
    term.grabInput();
512
    term.once('key', () => {
513
      term.releaseInput();
514
      showMainMenu();
515
    });
516
  });
517
}
518

519
// Start the application
520
showMainMenu();
521
```
522

523
### Multi-step Form
524

525
```javascript
526
const term = require('terminal-kit').terminal;
527

528
function collectUserInfo() {
529
  const user = {};
530
  
531
  // Step 1: Name
532
  term.cyan('Enter your name: ');
533
  term.inputField({ maxLength: 50 }, (error, name) => {
534
    user.name = name;
535
    
536
    // Step 2: Email
537
    term.cyan('\nEnter your email: ');
538
    term.inputField({ maxLength: 100 }, (error, email) => {
539
      user.email = email;
540
      
541
      // Step 3: Confirmation
542
      term.cyan('\nIs this information correct?\n');
543
      term.white('Name: %s\n', user.name);
544
      term.white('Email: %s\n', user.email);
545
      term.cyan('Confirm? [Y/n] ');
546
      
547
      term.yesOrNo({ default: true }, (error, confirmed) => {
548
        if (confirmed) {
549
          term.green('\nUser information saved!\n');
550
        } else {
551
          term.yellow('\nOperation cancelled.\n');
552
        }
553
      });
554
    });
555
  });
556
}
557

558
collectUserInfo();
559
```