termkit-ui 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +43 -0
- package/LICENSE +9 -0
- package/README.md +153 -2
- package/dist/components/display/layout.d.ts +91 -0
- package/dist/components/display/table.d.ts +53 -0
- package/dist/components/progress/index.d.ts +2 -0
- package/dist/components/progress/progressBar.d.ts +102 -0
- package/dist/components/progress/spinner.d.ts +107 -0
- package/dist/components/prompts/base.d.ts +53 -0
- package/dist/components/prompts/confirm.d.ts +46 -0
- package/dist/components/prompts/index.d.ts +6 -0
- package/dist/components/prompts/input.d.ts +46 -0
- package/dist/components/prompts/multiselect.d.ts +100 -0
- package/dist/components/prompts/number.d.ts +58 -0
- package/dist/components/prompts/password.d.ts +45 -0
- package/dist/components/prompts/select.d.ts +84 -0
- package/dist/core/ansi/escapes.d.ts +154 -0
- package/dist/core/caps/detect.d.ts +74 -0
- package/dist/core/errors/index.d.ts +73 -0
- package/dist/core/styles/index.d.ts +12 -0
- package/dist/core/width/string-width.d.ts +42 -0
- package/dist/engine/guard/terminal-guard.d.ts +84 -0
- package/dist/engine/keyboard/parser.d.ts +79 -0
- package/dist/engine/renderer/coordinator.d.ts +85 -0
- package/dist/index.d.ts +13 -0
- package/dist/testing/index.d.ts +127 -0
- package/package.json +77 -4
- package/src/components/display/layout.js +224 -0
- package/src/components/display/table.js +179 -0
- package/src/components/progress/index.js +6 -0
- package/src/components/progress/progressBar.js +153 -0
- package/src/components/progress/spinner.js +195 -0
- package/src/components/prompts/base.js +237 -0
- package/src/components/prompts/confirm.js +68 -0
- package/src/components/prompts/index.js +10 -0
- package/src/components/prompts/input.js +107 -0
- package/src/components/prompts/multiselect.js +205 -0
- package/src/components/prompts/number.js +140 -0
- package/src/components/prompts/password.js +77 -0
- package/src/components/prompts/select.js +171 -0
- package/src/core/ansi/escapes.js +52 -0
- package/src/core/caps/detect.js +167 -0
- package/src/core/errors/index.js +106 -0
- package/src/core/styles/index.js +174 -0
- package/src/core/width/string-width.js +244 -0
- package/src/engine/guard/terminal-guard.js +188 -0
- package/src/engine/keyboard/parser.js +285 -0
- package/src/engine/renderer/coordinator.js +263 -0
- package/src/index.js +17 -0
- package/src/testing/index.js +250 -0
|
@@ -0,0 +1,250 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Testing harness and virtual terminal simulator for TermKit consumers.
|
|
3
|
+
* Allows headless programmatic simulation of interactive CLI components.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
import { Readable, Writable } from 'node:stream';
|
|
7
|
+
import { stripAnsi } from '../core/width/string-width.js';
|
|
8
|
+
|
|
9
|
+
export class MockReadableStream extends Readable {
|
|
10
|
+
constructor() {
|
|
11
|
+
super();
|
|
12
|
+
/** @type {boolean} */
|
|
13
|
+
this.isTTY = true;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
_read() {}
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* Push raw string or buffer to stream.
|
|
20
|
+
* @param {string | Buffer} data
|
|
21
|
+
*/
|
|
22
|
+
sendData(data) {
|
|
23
|
+
this.push(data);
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Set raw mode mock.
|
|
28
|
+
* @param {boolean} mode
|
|
29
|
+
*/
|
|
30
|
+
setRawMode(mode) {
|
|
31
|
+
// Mock TTY raw mode hook
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
export class MockWritableStream extends Writable {
|
|
36
|
+
/**
|
|
37
|
+
* Mock writable stream with optional hermetic capability overrides.
|
|
38
|
+
* NOTE: Injecting capabilities is a testing-only mechanism to isolate tests
|
|
39
|
+
* from ambient environment variables and host TTY state.
|
|
40
|
+
* @param {Record<string, any>} [capabilities]
|
|
41
|
+
*/
|
|
42
|
+
constructor(capabilities = {}) {
|
|
43
|
+
super();
|
|
44
|
+
/** @type {string} */
|
|
45
|
+
this.buffer = '';
|
|
46
|
+
/** @type {boolean} */
|
|
47
|
+
this.isTTY = capabilities.isTTY !== undefined ? capabilities.isTTY : true;
|
|
48
|
+
/** @type {number} */
|
|
49
|
+
this.columns = capabilities.columns || 80;
|
|
50
|
+
/** @type {number} */
|
|
51
|
+
this.rows = capabilities.rows || 24;
|
|
52
|
+
/** @type {Record<string, any>} */
|
|
53
|
+
this.capabilities = capabilities;
|
|
54
|
+
/** @type {Record<string, any>} */
|
|
55
|
+
this._capabilities = capabilities;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* @param {any} chunk
|
|
60
|
+
* @param {string} encoding
|
|
61
|
+
* @param {() => void} callback
|
|
62
|
+
*/
|
|
63
|
+
_write(chunk, encoding, callback) {
|
|
64
|
+
this.buffer += chunk.toString();
|
|
65
|
+
callback();
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
clear() {
|
|
69
|
+
this.buffer = '';
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
getColorDepth() {
|
|
73
|
+
return this._capabilities.colorLevel === 3
|
|
74
|
+
? 24
|
|
75
|
+
: this._capabilities.colorLevel === 2
|
|
76
|
+
? 8
|
|
77
|
+
: this._capabilities.colorLevel === 1
|
|
78
|
+
? 4
|
|
79
|
+
: 1;
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
export class VirtualTerminal {
|
|
84
|
+
/**
|
|
85
|
+
* @param {Object} [options]
|
|
86
|
+
* @param {number} [options.columns=80]
|
|
87
|
+
* @param {number} [options.rows=24]
|
|
88
|
+
* @param {boolean} [options.isTTY=true]
|
|
89
|
+
* @param {Partial<import('../core/caps/detect.js').TerminalCapabilities>} [options.capabilities]
|
|
90
|
+
*/
|
|
91
|
+
constructor(options = {}) {
|
|
92
|
+
const isTTY = options.isTTY !== undefined ? options.isTTY : true;
|
|
93
|
+
const columns = options.columns || 80;
|
|
94
|
+
const rows = options.rows || 24;
|
|
95
|
+
|
|
96
|
+
const defaultCaps = {
|
|
97
|
+
colorLevel: 0,
|
|
98
|
+
hasColor: false,
|
|
99
|
+
has256: false,
|
|
100
|
+
hasTrueColor: false,
|
|
101
|
+
unicode: true,
|
|
102
|
+
isTTY,
|
|
103
|
+
isCI: false,
|
|
104
|
+
isDumb: false,
|
|
105
|
+
columns,
|
|
106
|
+
rows,
|
|
107
|
+
reducedMotion: false,
|
|
108
|
+
...options.capabilities
|
|
109
|
+
};
|
|
110
|
+
|
|
111
|
+
/** @type {MockReadableStream} */
|
|
112
|
+
this.stdin = new MockReadableStream();
|
|
113
|
+
/** @type {MockWritableStream} */
|
|
114
|
+
this.stdout = new MockWritableStream(defaultCaps);
|
|
115
|
+
/** @type {MockWritableStream} */
|
|
116
|
+
this.stderr = new MockWritableStream(defaultCaps);
|
|
117
|
+
|
|
118
|
+
this.stdin.isTTY = isTTY;
|
|
119
|
+
this.stdout.isTTY = isTTY;
|
|
120
|
+
this.stderr.isTTY = isTTY;
|
|
121
|
+
|
|
122
|
+
this.stdout.columns = columns;
|
|
123
|
+
this.stdout.rows = rows;
|
|
124
|
+
this.stderr.columns = columns;
|
|
125
|
+
this.stderr.rows = rows;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* Type text into stdin.
|
|
130
|
+
* @param {string} text
|
|
131
|
+
* @returns {Promise<void>}
|
|
132
|
+
*/
|
|
133
|
+
async type(text) {
|
|
134
|
+
this.stdin.sendData(text);
|
|
135
|
+
await new Promise((r) => setImmediate(r));
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* Send key event sequence into stdin.
|
|
140
|
+
* @param {string} name
|
|
141
|
+
* @param {Object} [modifiers]
|
|
142
|
+
* @param {boolean} [modifiers.ctrl]
|
|
143
|
+
* @param {boolean} [modifiers.meta]
|
|
144
|
+
* @param {boolean} [modifiers.shift]
|
|
145
|
+
* @returns {Promise<void>}
|
|
146
|
+
*/
|
|
147
|
+
async pressKey(name, modifiers = {}) {
|
|
148
|
+
if (modifiers.ctrl) {
|
|
149
|
+
if (name === 'c') {
|
|
150
|
+
this.stdin.sendData('\x03');
|
|
151
|
+
} else if (name === 'd') {
|
|
152
|
+
this.stdin.sendData('\x04');
|
|
153
|
+
} else {
|
|
154
|
+
const code = name.charCodeAt(0) - 96;
|
|
155
|
+
this.stdin.sendData(String.fromCharCode(code));
|
|
156
|
+
}
|
|
157
|
+
} else if (name === 'return' || name === 'enter') {
|
|
158
|
+
this.stdin.sendData('\r');
|
|
159
|
+
} else if (name === 'up') {
|
|
160
|
+
this.stdin.sendData('\x1b[A');
|
|
161
|
+
} else if (name === 'down') {
|
|
162
|
+
this.stdin.sendData('\x1b[B');
|
|
163
|
+
} else if (name === 'right') {
|
|
164
|
+
this.stdin.sendData('\x1b[C');
|
|
165
|
+
} else if (name === 'left') {
|
|
166
|
+
this.stdin.sendData('\x1b[D');
|
|
167
|
+
} else if (name === 'escape') {
|
|
168
|
+
this.stdin.sendData('\x1b');
|
|
169
|
+
} else if (name === 'space') {
|
|
170
|
+
this.stdin.sendData(' ');
|
|
171
|
+
} else if (name === 'backspace') {
|
|
172
|
+
this.stdin.sendData('\x7f');
|
|
173
|
+
} else {
|
|
174
|
+
this.stdin.sendData(name);
|
|
175
|
+
}
|
|
176
|
+
await new Promise((r) => setImmediate(r));
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
async pressEnter() {
|
|
180
|
+
return this.pressKey('return');
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
async pressArrowDown() {
|
|
184
|
+
return this.pressKey('down');
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
async pressArrowUp() {
|
|
188
|
+
return this.pressKey('up');
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
async pressSpace() {
|
|
192
|
+
return this.pressKey('space');
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
async pressCtrlC() {
|
|
196
|
+
return this.pressKey('c', { ctrl: true });
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
async pressEscape() {
|
|
200
|
+
return this.pressKey('escape');
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/**
|
|
204
|
+
* Get output text with ANSI sequences stripped.
|
|
205
|
+
* Pass { raw: true } to preserve raw ANSI escape sequences.
|
|
206
|
+
* @param {'stdout' | 'stderr'} [stream='stderr']
|
|
207
|
+
* @param {Object} [options]
|
|
208
|
+
* @param {boolean} [options.raw=false]
|
|
209
|
+
* @returns {string}
|
|
210
|
+
*/
|
|
211
|
+
getText(stream = 'stderr', options = {}) {
|
|
212
|
+
const raw = stream === 'stdout' ? this.stdout.buffer : this.stderr.buffer;
|
|
213
|
+
return options.raw ? raw : stripAnsi(raw);
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
/**
|
|
217
|
+
* Get raw unstripped output text including ANSI escape sequences.
|
|
218
|
+
* @param {'stdout' | 'stderr'} [stream='stderr']
|
|
219
|
+
* @returns {string}
|
|
220
|
+
*/
|
|
221
|
+
getRawText(stream = 'stderr') {
|
|
222
|
+
return stream === 'stdout' ? this.stdout.buffer : this.stderr.buffer;
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
/**
|
|
226
|
+
* Get cleaned output lines with ANSI stripped.
|
|
227
|
+
* @param {'stdout' | 'stderr'} [stream='stderr']
|
|
228
|
+
* @returns {string[]}
|
|
229
|
+
*/
|
|
230
|
+
getLines(stream = 'stderr') {
|
|
231
|
+
return this.getText(stream).split('\n');
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
/**
|
|
235
|
+
* Clear capture buffers.
|
|
236
|
+
*/
|
|
237
|
+
clear() {
|
|
238
|
+
this.stdout.clear();
|
|
239
|
+
this.stderr.clear();
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
/**
|
|
244
|
+
* Factory to create an isolated VirtualTerminal.
|
|
245
|
+
* @param {Object} [options]
|
|
246
|
+
* @returns {VirtualTerminal}
|
|
247
|
+
*/
|
|
248
|
+
export function createTestTerminal(options) {
|
|
249
|
+
return new VirtualTerminal(options);
|
|
250
|
+
}
|