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.
Files changed (50) hide show
  1. package/CHANGELOG.md +43 -0
  2. package/LICENSE +9 -0
  3. package/README.md +153 -2
  4. package/dist/components/display/layout.d.ts +91 -0
  5. package/dist/components/display/table.d.ts +53 -0
  6. package/dist/components/progress/index.d.ts +2 -0
  7. package/dist/components/progress/progressBar.d.ts +102 -0
  8. package/dist/components/progress/spinner.d.ts +107 -0
  9. package/dist/components/prompts/base.d.ts +53 -0
  10. package/dist/components/prompts/confirm.d.ts +46 -0
  11. package/dist/components/prompts/index.d.ts +6 -0
  12. package/dist/components/prompts/input.d.ts +46 -0
  13. package/dist/components/prompts/multiselect.d.ts +100 -0
  14. package/dist/components/prompts/number.d.ts +58 -0
  15. package/dist/components/prompts/password.d.ts +45 -0
  16. package/dist/components/prompts/select.d.ts +84 -0
  17. package/dist/core/ansi/escapes.d.ts +154 -0
  18. package/dist/core/caps/detect.d.ts +74 -0
  19. package/dist/core/errors/index.d.ts +73 -0
  20. package/dist/core/styles/index.d.ts +12 -0
  21. package/dist/core/width/string-width.d.ts +42 -0
  22. package/dist/engine/guard/terminal-guard.d.ts +84 -0
  23. package/dist/engine/keyboard/parser.d.ts +79 -0
  24. package/dist/engine/renderer/coordinator.d.ts +85 -0
  25. package/dist/index.d.ts +13 -0
  26. package/dist/testing/index.d.ts +127 -0
  27. package/package.json +77 -4
  28. package/src/components/display/layout.js +224 -0
  29. package/src/components/display/table.js +179 -0
  30. package/src/components/progress/index.js +6 -0
  31. package/src/components/progress/progressBar.js +153 -0
  32. package/src/components/progress/spinner.js +195 -0
  33. package/src/components/prompts/base.js +237 -0
  34. package/src/components/prompts/confirm.js +68 -0
  35. package/src/components/prompts/index.js +10 -0
  36. package/src/components/prompts/input.js +107 -0
  37. package/src/components/prompts/multiselect.js +205 -0
  38. package/src/components/prompts/number.js +140 -0
  39. package/src/components/prompts/password.js +77 -0
  40. package/src/components/prompts/select.js +171 -0
  41. package/src/core/ansi/escapes.js +52 -0
  42. package/src/core/caps/detect.js +167 -0
  43. package/src/core/errors/index.js +106 -0
  44. package/src/core/styles/index.js +174 -0
  45. package/src/core/width/string-width.js +244 -0
  46. package/src/engine/guard/terminal-guard.js +188 -0
  47. package/src/engine/keyboard/parser.js +285 -0
  48. package/src/engine/renderer/coordinator.js +263 -0
  49. package/src/index.js +17 -0
  50. 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
+ }