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
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [0.1.0] - 2026-11-21
|
|
9
|
+
|
|
10
|
+
### Changed
|
|
11
|
+
- **Type Definitions & Prompt Signatures**:
|
|
12
|
+
- Precision prompt return types: `input`, `password`, `number`, `confirm`, `select`, and `multiselect` now return `Promise<T>` by default (or with `onCancel: 'throw'`) and `Promise<T | null>` when `onCancel: 'return-null'`.
|
|
13
|
+
- Generic option value inference for `select` and `multiselect`, accurately typing literal unions when `items` are passed `as const`.
|
|
14
|
+
- Added `@types/node` as an optional `peerDependency` (`peerDependenciesMeta optional: true`) to resolve Node.js global and module types in consumer TypeScript projects.
|
|
15
|
+
- Added full `@ts-expect-error` typing guard test coverage for all prompts (`input`, `password`, `number`, `confirm`, `select`, `multiselect`) in `scripts/test-package.js`.
|
|
16
|
+
- **Terminal Safety & Render Callbacks**:
|
|
17
|
+
- `LiveRegion.prototype.render` now accepts render callback functions and guarantees synchronous terminal restoration (`terminalGuard.restore()`) if a render callback throws.
|
|
18
|
+
- `runPrompt` wraps initial and keypress render callbacks with immediate cleanup and rejection.
|
|
19
|
+
- Added real process-level child process tests in `test/integration/terminal-safety.test.js` validating guaranteed cursor, raw mode, and exit code restoration across SIGINT (130), SIGTERM (143), uncaught exceptions (1), render errors (1), normal exits (0), double key-session closes (0), and stdin stream closure / EOF (`CancelError:stream-closed` with prompt hang prevention).
|
|
20
|
+
|
|
21
|
+
### Added
|
|
22
|
+
- **Core Engine & Architecture**:
|
|
23
|
+
- Centralized `OutputCoordinator` with diffed line redrawing and safe concurrent logging.
|
|
24
|
+
- Fail-safe `TerminalGuard` with guaranteed restoration of raw mode and cursor visibility.
|
|
25
|
+
- Zero-dependency ANSI string width calculator (`stringWidth`) handling grapheme clusters via `Intl.Segmenter`, East Asian Width, emojis, and ZWJ sequences.
|
|
26
|
+
- Nesting-safe ANSI color styling engine (`style`, `colors`) with automatic degradation across color levels 3, 2, 1, and 0.
|
|
27
|
+
- High-performance `KeyboardParser` with bracketed paste mode support.
|
|
28
|
+
- **Interactive Prompts (`termkit/prompts`)**:
|
|
29
|
+
- `confirm`: Boolean toggle prompt with arrow keys and Y/n shortcuts.
|
|
30
|
+
- `input`: Text input prompt with placeholder, default, and inline validation.
|
|
31
|
+
- `password`: Masked secret input prompt with strict zero-leakage security.
|
|
32
|
+
- `number`: Numeric input prompt with bounds checking, stepping, and integer/float parsing.
|
|
33
|
+
- `select`: Vertical selection menu with paging, looping, and disabled item support.
|
|
34
|
+
- `multiselect`: Checkbox multiple choice prompt with space-toggle, invert, and select-all.
|
|
35
|
+
- **Progress Indicators (`termkit/progress`)**:
|
|
36
|
+
- `spinner`: Animated Braille spinner with states (`succeed`, `fail`, `warn`, `info`) and non-TTY static milestones.
|
|
37
|
+
- `progressBar`: Single progress bar with percentage, ETA calculation, and milestone reporting.
|
|
38
|
+
- **Layout & Tables (`termkit/layout`, `termkit/tables`)**:
|
|
39
|
+
- `box`: Styled terminal container with custom borders, padding, margins, and title alignments.
|
|
40
|
+
- `divider`: Horizontal divider rule with optional title.
|
|
41
|
+
- `table`: Tabular data formatter with column alignment and Unicode/ASCII borders.
|
|
42
|
+
- **Testing Harness (`termkit/testing`)**:
|
|
43
|
+
- `createTestTerminal` / `VirtualTerminal` for in-memory headless testing of interactive CLI workflows.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Sagar
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
6
|
+
|
|
7
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
8
|
+
|
|
9
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,154 @@
|
|
|
1
|
-
#
|
|
1
|
+
# TermKit
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> Zero-dependency, cohesive TypeScript/ESM toolkit for building robust Node.js CLI user interfaces.
|
|
4
|
+
|
|
5
|
+
[](https://github.com/hexqbv/TermKit/actions/workflows/ci.yml)
|
|
6
|
+
[](https://nodejs.org)
|
|
7
|
+
[](LICENSE)
|
|
8
|
+
[](docs/planning/05-dependencies.md)
|
|
9
|
+
|
|
10
|
+
TermKit unifies interactive prompts, progress indicators, styled boxes, and data tables on a **shared virtual screen renderer** that guarantees:
|
|
11
|
+
- **Collision-free concurrent logging**: Asynchronous worker logs never tear running spinners or prompts.
|
|
12
|
+
- **Fail-safe terminal restoration**: Raw mode and cursor visibility are restored on every exit path, normal completion, cancellation, and unhandled exception.
|
|
13
|
+
- **Clean UNIX pipelines**: Prompts and spinners write to `stderr` by default, keeping `stdout` dedicated strictly to machine data.
|
|
14
|
+
- **Predictable non-interactive/CI behavior**: Prompts resolve to defaults or throw typed `NonInteractiveError` without hanging.
|
|
15
|
+
- **Built-in headless testing harness**: Test interactive CLI prompts in memory without spawning PTYs.
|
|
16
|
+
- **Zero runtime dependencies**: Pure ESM, sub-millisecond startup, minimal footprint.
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Installation
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npm install termkit-ui
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
*(Requires Node.js `>= 22.0.0`)*
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## Quick Start
|
|
31
|
+
|
|
32
|
+
### 1. Interactive Prompts (`termkit-ui/prompts`)
|
|
33
|
+
|
|
34
|
+
```javascript
|
|
35
|
+
import { input, select, confirm } from 'termkit-ui/prompts';
|
|
36
|
+
|
|
37
|
+
const name = await input({
|
|
38
|
+
message: 'Project name:',
|
|
39
|
+
default: 'my-app'
|
|
40
|
+
});
|
|
41
|
+
|
|
42
|
+
const template = await select({
|
|
43
|
+
message: 'Choose framework:',
|
|
44
|
+
items: [
|
|
45
|
+
{ label: 'React', value: 'react' },
|
|
46
|
+
{ label: 'Vue', value: 'vue' },
|
|
47
|
+
{ label: 'Svelte', value: 'svelte' }
|
|
48
|
+
]
|
|
49
|
+
});
|
|
50
|
+
|
|
51
|
+
const proceed = await confirm({
|
|
52
|
+
message: 'Initialize git repository?',
|
|
53
|
+
default: true
|
|
54
|
+
});
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### 2. Animated Spinner with Concurrent Logging (`termkit-ui/progress`)
|
|
58
|
+
|
|
59
|
+
```javascript
|
|
60
|
+
import { spinner } from 'termkit-ui/progress';
|
|
61
|
+
import { defaultCoordinator } from 'termkit-ui';
|
|
62
|
+
|
|
63
|
+
const s = spinner('Deploying application...').start();
|
|
64
|
+
|
|
65
|
+
// Background logs can safely write without tearing active spinner line
|
|
66
|
+
defaultCoordinator.log('Uploading artifact: 14.2 MB');
|
|
67
|
+
|
|
68
|
+
s.succeed('Deployment complete!');
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### 3. Styled Boxes and Data Tables (`termkit-ui/layout`, `termkit-ui/tables`)
|
|
72
|
+
|
|
73
|
+
```javascript
|
|
74
|
+
import { box, divider } from 'termkit-ui/layout';
|
|
75
|
+
import { table } from 'termkit-ui/tables';
|
|
76
|
+
import { style } from 'termkit-ui/styles';
|
|
77
|
+
|
|
78
|
+
console.log(
|
|
79
|
+
box(
|
|
80
|
+
`Status: ${style.green('HEALTHY')}\nCluster: us-east-1`,
|
|
81
|
+
{ title: 'SERVER METRICS', borderColor: 'green' }
|
|
82
|
+
)
|
|
83
|
+
);
|
|
84
|
+
|
|
85
|
+
const users = [
|
|
86
|
+
{ id: 1, name: 'Alice', role: 'Admin' },
|
|
87
|
+
{ id: 2, name: 'Bob', role: 'Developer' }
|
|
88
|
+
];
|
|
89
|
+
|
|
90
|
+
console.log(table(users, { borderStyle: 'rounded' }));
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## Modular Subpath Exports
|
|
96
|
+
|
|
97
|
+
TermKit is modular and tree-shakeable (`"sideEffects": false`):
|
|
98
|
+
|
|
99
|
+
| Import Specifier | Primary Symbols |
|
|
100
|
+
| :--- | :--- |
|
|
101
|
+
| `termkit-ui` | Primary barrel re-exporting common helpers |
|
|
102
|
+
| `termkit-ui/prompts` | `confirm`, `input`, `password`, `number`, `select`, `multiselect` |
|
|
103
|
+
| `termkit-ui/progress` | `spinner`, `progressBar` |
|
|
104
|
+
| `termkit-ui/styles` | `style`, `colors`, `stringWidth`, `stripAnsi`, `truncate`, `wrapText` |
|
|
105
|
+
| `termkit-ui/layout` | `box`, `divider` |
|
|
106
|
+
| `termkit-ui/tables` | `table` |
|
|
107
|
+
| `termkit-ui/testing` | `createTestTerminal`, `VirtualTerminal`, `MockStream` |
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
## Headless Unit Testing for Consumers
|
|
112
|
+
|
|
113
|
+
TermKit includes a first-class virtual terminal harness so you can unit-test your CLI workflows in memory:
|
|
114
|
+
|
|
115
|
+
```javascript
|
|
116
|
+
import { test } from 'node:test';
|
|
117
|
+
import assert from 'node:assert/strict';
|
|
118
|
+
import { createTestTerminal } from 'termkit-ui/testing';
|
|
119
|
+
import { confirm } from 'termkit-ui/prompts';
|
|
120
|
+
|
|
121
|
+
test('my cli prompt test', async () => {
|
|
122
|
+
const term = createTestTerminal();
|
|
123
|
+
|
|
124
|
+
const promise = confirm({
|
|
125
|
+
message: 'Proceed?',
|
|
126
|
+
input: term.stdin,
|
|
127
|
+
output: term.stderr
|
|
128
|
+
});
|
|
129
|
+
|
|
130
|
+
await term.type('y');
|
|
131
|
+
const result = await promise;
|
|
132
|
+
assert.equal(result, true);
|
|
133
|
+
});
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## TypeScript
|
|
139
|
+
|
|
140
|
+
TermKit ships with TypeScript declarations generated directly from source JSDoc (`dist/*.d.ts`), supporting `"moduleResolution": "nodenext"` and strict typechecking.
|
|
141
|
+
|
|
142
|
+
Because TermKit types reference Node.js primitives (`NodeJS.ReadableStream`, `NodeJS.WritableStream`, `Buffer`, `node:stream`, `node:events`), consumer TypeScript projects require `@types/node` in development:
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
npm install --save-dev @types/node
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
`@types/node` is declared as an optional `peerDependency` (`peerDependenciesMeta optional: true`) and is never installed automatically at runtime.
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## License
|
|
153
|
+
|
|
154
|
+
MIT © Sagar
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @typedef {Object} BoxPadding
|
|
3
|
+
* @property {number} [top=0]
|
|
4
|
+
* @property {number} [bottom=0]
|
|
5
|
+
* @property {number} [left=1]
|
|
6
|
+
* @property {number} [right=1]
|
|
7
|
+
*/
|
|
8
|
+
/**
|
|
9
|
+
* @typedef {Object} BoxOptions
|
|
10
|
+
* @property {string} [title] - Optional box title
|
|
11
|
+
* @property {'left' | 'center' | 'right'} [titleAlign='left']
|
|
12
|
+
* @property {'single' | 'double' | 'rounded' | 'bold' | 'ascii'} [borderStyle='rounded']
|
|
13
|
+
* @property {string} [borderColor] - Border color (e.g. 'cyan', 'green', 'dim')
|
|
14
|
+
* @property {number | BoxPadding} [padding=0]
|
|
15
|
+
* @property {number} [width] - Explicit box width
|
|
16
|
+
* @property {'left' | 'center' | 'right'} [align='left']
|
|
17
|
+
* @property {Partial<import('../../core/caps/detect.js').TerminalCapabilities>} [capabilities] - Override detected capabilities (testing only)
|
|
18
|
+
*/
|
|
19
|
+
/**
|
|
20
|
+
* Format string content inside a styled terminal box.
|
|
21
|
+
* @param {string} content
|
|
22
|
+
* @param {BoxOptions} [options={}]
|
|
23
|
+
* @returns {string}
|
|
24
|
+
*/
|
|
25
|
+
export function box(content: string, options?: BoxOptions): string;
|
|
26
|
+
/**
|
|
27
|
+
* @typedef {Object} DividerOptions
|
|
28
|
+
* @property {string} [title] - Optional title
|
|
29
|
+
* @property {'left' | 'center' | 'right'} [titleAlign='center']
|
|
30
|
+
* @property {string} [character='─'] - Divider character
|
|
31
|
+
* @property {string} [color='dim'] - Color style
|
|
32
|
+
* @property {number} [width] - Divider length (defaults to terminal columns)
|
|
33
|
+
* @property {Partial<import('../../core/caps/detect.js').TerminalCapabilities>} [capabilities] - Override detected capabilities (testing only)
|
|
34
|
+
*/
|
|
35
|
+
/**
|
|
36
|
+
* Create a horizontal divider rule.
|
|
37
|
+
* @param {DividerOptions | string} [options='']
|
|
38
|
+
* @returns {string}
|
|
39
|
+
*/
|
|
40
|
+
export function divider(options?: DividerOptions | string): string;
|
|
41
|
+
export type BoxPadding = {
|
|
42
|
+
top?: number | undefined;
|
|
43
|
+
bottom?: number | undefined;
|
|
44
|
+
left?: number | undefined;
|
|
45
|
+
right?: number | undefined;
|
|
46
|
+
};
|
|
47
|
+
export type BoxOptions = {
|
|
48
|
+
/**
|
|
49
|
+
* - Optional box title
|
|
50
|
+
*/
|
|
51
|
+
title?: string | undefined;
|
|
52
|
+
titleAlign?: "right" | "left" | "center" | undefined;
|
|
53
|
+
borderStyle?: "ascii" | "bold" | "single" | "double" | "rounded" | undefined;
|
|
54
|
+
/**
|
|
55
|
+
* - Border color (e.g. 'cyan', 'green', 'dim')
|
|
56
|
+
*/
|
|
57
|
+
borderColor?: string | undefined;
|
|
58
|
+
padding?: number | BoxPadding | undefined;
|
|
59
|
+
/**
|
|
60
|
+
* - Explicit box width
|
|
61
|
+
*/
|
|
62
|
+
width?: number | undefined;
|
|
63
|
+
align?: "right" | "left" | "center" | undefined;
|
|
64
|
+
/**
|
|
65
|
+
* - Override detected capabilities (testing only)
|
|
66
|
+
*/
|
|
67
|
+
capabilities?: Partial<import("../../core/caps/detect.js").TerminalCapabilities> | undefined;
|
|
68
|
+
};
|
|
69
|
+
export type DividerOptions = {
|
|
70
|
+
/**
|
|
71
|
+
* - Optional title
|
|
72
|
+
*/
|
|
73
|
+
title?: string | undefined;
|
|
74
|
+
titleAlign?: "right" | "left" | "center" | undefined;
|
|
75
|
+
/**
|
|
76
|
+
* - Divider character
|
|
77
|
+
*/
|
|
78
|
+
character?: string | undefined;
|
|
79
|
+
/**
|
|
80
|
+
* - Color style
|
|
81
|
+
*/
|
|
82
|
+
color?: string | undefined;
|
|
83
|
+
/**
|
|
84
|
+
* - Divider length (defaults to terminal columns)
|
|
85
|
+
*/
|
|
86
|
+
width?: number | undefined;
|
|
87
|
+
/**
|
|
88
|
+
* - Override detected capabilities (testing only)
|
|
89
|
+
*/
|
|
90
|
+
capabilities?: Partial<import("../../core/caps/detect.js").TerminalCapabilities> | undefined;
|
|
91
|
+
};
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @typedef {Object} TableColumn
|
|
3
|
+
* @property {string} key - Object key or column id
|
|
4
|
+
* @property {string} header - Display header title
|
|
5
|
+
* @property {'left' | 'center' | 'right'} [align='left']
|
|
6
|
+
* @property {number} [width] - Fixed width
|
|
7
|
+
*/
|
|
8
|
+
/**
|
|
9
|
+
* @typedef {Object} TableOptions
|
|
10
|
+
* @property {Array<TableColumn | string>} [columns] - Explicit column definitions
|
|
11
|
+
* @property {'single' | 'rounded' | 'ascii'} [borderStyle='rounded']
|
|
12
|
+
* @property {boolean} [compact=false]
|
|
13
|
+
* @property {number} [width] - Constrain total table width to this many columns
|
|
14
|
+
* @property {Partial<import('../../core/caps/detect.js').TerminalCapabilities>} [capabilities] - Override detected capabilities (testing only)
|
|
15
|
+
*/
|
|
16
|
+
/**
|
|
17
|
+
* Format tabular rows into an aligned visual table.
|
|
18
|
+
* @param {Array<Record<string, any> | any[]>} rows
|
|
19
|
+
* @param {TableOptions} [options={}]
|
|
20
|
+
* @returns {string}
|
|
21
|
+
*/
|
|
22
|
+
export function table(rows: Array<Record<string, any> | any[]>, options?: TableOptions): string;
|
|
23
|
+
export type TableColumn = {
|
|
24
|
+
/**
|
|
25
|
+
* - Object key or column id
|
|
26
|
+
*/
|
|
27
|
+
key: string;
|
|
28
|
+
/**
|
|
29
|
+
* - Display header title
|
|
30
|
+
*/
|
|
31
|
+
header: string;
|
|
32
|
+
align?: "right" | "left" | "center" | undefined;
|
|
33
|
+
/**
|
|
34
|
+
* - Fixed width
|
|
35
|
+
*/
|
|
36
|
+
width?: number | undefined;
|
|
37
|
+
};
|
|
38
|
+
export type TableOptions = {
|
|
39
|
+
/**
|
|
40
|
+
* - Explicit column definitions
|
|
41
|
+
*/
|
|
42
|
+
columns?: (string | TableColumn)[] | undefined;
|
|
43
|
+
borderStyle?: "ascii" | "single" | "rounded" | undefined;
|
|
44
|
+
compact?: boolean | undefined;
|
|
45
|
+
/**
|
|
46
|
+
* - Constrain total table width to this many columns
|
|
47
|
+
*/
|
|
48
|
+
width?: number | undefined;
|
|
49
|
+
/**
|
|
50
|
+
* - Override detected capabilities (testing only)
|
|
51
|
+
*/
|
|
52
|
+
capabilities?: Partial<import("../../core/caps/detect.js").TerminalCapabilities> | undefined;
|
|
53
|
+
};
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Factory to create a progress bar.
|
|
3
|
+
* @param {ProgressBarOptions} options
|
|
4
|
+
* @returns {ProgressBar}
|
|
5
|
+
*/
|
|
6
|
+
export function progressBar(options: ProgressBarOptions): ProgressBar;
|
|
7
|
+
/**
|
|
8
|
+
* @typedef {Object} ProgressBarOptions
|
|
9
|
+
* @property {number} total - Total ticks / units
|
|
10
|
+
* @property {string} [message=''] - Label text
|
|
11
|
+
* @property {number} [width=30] - Width of the bar in columns
|
|
12
|
+
* @property {NodeJS.WritableStream} [stream] - Defaults to process.stderr
|
|
13
|
+
* @property {boolean} [showEta=true] - Display ETA calculation
|
|
14
|
+
* @property {boolean} [showPercentage=true] - Display percentage
|
|
15
|
+
* @property {boolean} [accessible] - Force accessible milestone mode
|
|
16
|
+
*/
|
|
17
|
+
export class ProgressBar {
|
|
18
|
+
/**
|
|
19
|
+
* @param {ProgressBarOptions} options
|
|
20
|
+
*/
|
|
21
|
+
constructor(options: ProgressBarOptions);
|
|
22
|
+
/** @type {number} */
|
|
23
|
+
total: number;
|
|
24
|
+
/** @type {number} */
|
|
25
|
+
current: number;
|
|
26
|
+
/** @type {string} */
|
|
27
|
+
message: string;
|
|
28
|
+
/** @type {number} */
|
|
29
|
+
barWidth: number;
|
|
30
|
+
/** @type {NodeJS.WritableStream} */
|
|
31
|
+
stream: NodeJS.WritableStream;
|
|
32
|
+
/** @type {boolean} */
|
|
33
|
+
showEta: boolean;
|
|
34
|
+
/** @type {boolean} */
|
|
35
|
+
showPercentage: boolean;
|
|
36
|
+
/** @type {boolean} */
|
|
37
|
+
isAccessible: boolean;
|
|
38
|
+
/** @type {boolean} */
|
|
39
|
+
useUnicode: boolean;
|
|
40
|
+
/** @type {number} */
|
|
41
|
+
startTime: number;
|
|
42
|
+
/** @type {number} */
|
|
43
|
+
_lastMilestone: number;
|
|
44
|
+
/** @type {OutputCoordinator} */
|
|
45
|
+
coordinator: OutputCoordinator;
|
|
46
|
+
/** @type {import('../../engine/renderer/coordinator.js').LiveRegion | null} */
|
|
47
|
+
_region: import("../../engine/renderer/coordinator.js").LiveRegion | null;
|
|
48
|
+
/** @type {boolean} */
|
|
49
|
+
_active: boolean;
|
|
50
|
+
/**
|
|
51
|
+
* Start or update progress.
|
|
52
|
+
* @param {number} current
|
|
53
|
+
* @param {string} [message]
|
|
54
|
+
*/
|
|
55
|
+
update(current: number, message?: string): void;
|
|
56
|
+
/**
|
|
57
|
+
* Increment progress by amount.
|
|
58
|
+
* @param {number} [amount=1]
|
|
59
|
+
* @param {string} [message]
|
|
60
|
+
*/
|
|
61
|
+
increment(amount?: number, message?: string): void;
|
|
62
|
+
/**
|
|
63
|
+
* Complete the progress bar.
|
|
64
|
+
* @param {string} [message]
|
|
65
|
+
*/
|
|
66
|
+
complete(message?: string): void;
|
|
67
|
+
/**
|
|
68
|
+
* Stop and unmount the progress bar.
|
|
69
|
+
*/
|
|
70
|
+
stop(): void;
|
|
71
|
+
}
|
|
72
|
+
export type ProgressBarOptions = {
|
|
73
|
+
/**
|
|
74
|
+
* - Total ticks / units
|
|
75
|
+
*/
|
|
76
|
+
total: number;
|
|
77
|
+
/**
|
|
78
|
+
* - Label text
|
|
79
|
+
*/
|
|
80
|
+
message?: string | undefined;
|
|
81
|
+
/**
|
|
82
|
+
* - Width of the bar in columns
|
|
83
|
+
*/
|
|
84
|
+
width?: number | undefined;
|
|
85
|
+
/**
|
|
86
|
+
* - Defaults to process.stderr
|
|
87
|
+
*/
|
|
88
|
+
stream?: NodeJS.WritableStream | undefined;
|
|
89
|
+
/**
|
|
90
|
+
* - Display ETA calculation
|
|
91
|
+
*/
|
|
92
|
+
showEta?: boolean | undefined;
|
|
93
|
+
/**
|
|
94
|
+
* - Display percentage
|
|
95
|
+
*/
|
|
96
|
+
showPercentage?: boolean | undefined;
|
|
97
|
+
/**
|
|
98
|
+
* - Force accessible milestone mode
|
|
99
|
+
*/
|
|
100
|
+
accessible?: boolean | undefined;
|
|
101
|
+
};
|
|
102
|
+
import { OutputCoordinator } from '../../engine/renderer/coordinator.js';
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Factory to create a spinner.
|
|
3
|
+
* @param {SpinnerOptions | string} [options]
|
|
4
|
+
* @returns {Spinner}
|
|
5
|
+
*/
|
|
6
|
+
export function spinner(options?: SpinnerOptions | string): Spinner;
|
|
7
|
+
/**
|
|
8
|
+
* @typedef {Object} SpinnerOptions
|
|
9
|
+
* @property {string} [message=''] - Initial loading text
|
|
10
|
+
* @property {NodeJS.WritableStream} [stream] - Defaults to process.stderr
|
|
11
|
+
* @property {string} [color='cyan'] - Color of the spinner glyph
|
|
12
|
+
* @property {boolean} [accessible] - Force accessible static mode
|
|
13
|
+
*/
|
|
14
|
+
export class Spinner {
|
|
15
|
+
/**
|
|
16
|
+
* @param {SpinnerOptions | string} [options='']
|
|
17
|
+
*/
|
|
18
|
+
constructor(options?: SpinnerOptions | string);
|
|
19
|
+
/** @type {string} */
|
|
20
|
+
message: string;
|
|
21
|
+
/** @type {NodeJS.WritableStream} */
|
|
22
|
+
stream: NodeJS.WritableStream;
|
|
23
|
+
/** @type {string} */
|
|
24
|
+
color: string;
|
|
25
|
+
/** @type {boolean} */
|
|
26
|
+
isSpinning: boolean;
|
|
27
|
+
/** @type {boolean} */
|
|
28
|
+
isAccessible: boolean;
|
|
29
|
+
/** @type {string[]} */
|
|
30
|
+
frames: string[];
|
|
31
|
+
/** @type {number} */
|
|
32
|
+
_frameIndex: number;
|
|
33
|
+
/** @type {NodeJS.Timeout | null} */
|
|
34
|
+
_timer: NodeJS.Timeout | null;
|
|
35
|
+
/** @type {OutputCoordinator} */
|
|
36
|
+
coordinator: OutputCoordinator;
|
|
37
|
+
/** @type {import('../../engine/renderer/coordinator.js').LiveRegion | null} */
|
|
38
|
+
_region: import("../../engine/renderer/coordinator.js").LiveRegion | null;
|
|
39
|
+
/** @type {(() => void) | null} */
|
|
40
|
+
_unregisterGuard: (() => void) | null;
|
|
41
|
+
/**
|
|
42
|
+
* Start the spinner.
|
|
43
|
+
* @param {string} [message]
|
|
44
|
+
* @returns {Spinner}
|
|
45
|
+
*/
|
|
46
|
+
start(message?: string): Spinner;
|
|
47
|
+
/**
|
|
48
|
+
* @private
|
|
49
|
+
*/
|
|
50
|
+
private _renderFrame;
|
|
51
|
+
/**
|
|
52
|
+
* Update the spinner message while running.
|
|
53
|
+
* @param {string} message
|
|
54
|
+
* @returns {Spinner}
|
|
55
|
+
*/
|
|
56
|
+
update(message: string): Spinner;
|
|
57
|
+
/**
|
|
58
|
+
* Stop the spinner and clear active line.
|
|
59
|
+
*/
|
|
60
|
+
stop(): void;
|
|
61
|
+
/**
|
|
62
|
+
* Complete with success state.
|
|
63
|
+
* @param {string} [message]
|
|
64
|
+
*/
|
|
65
|
+
succeed(message?: string): void;
|
|
66
|
+
/**
|
|
67
|
+
* Complete with failure state.
|
|
68
|
+
* @param {string} [message]
|
|
69
|
+
*/
|
|
70
|
+
fail(message?: string): void;
|
|
71
|
+
/**
|
|
72
|
+
* Complete with warning state.
|
|
73
|
+
* @param {string} [message]
|
|
74
|
+
*/
|
|
75
|
+
warn(message?: string): void;
|
|
76
|
+
/**
|
|
77
|
+
* Complete with info state.
|
|
78
|
+
* @param {string} [message]
|
|
79
|
+
*/
|
|
80
|
+
info(message?: string): void;
|
|
81
|
+
/**
|
|
82
|
+
* @private
|
|
83
|
+
* @param {string | undefined} message
|
|
84
|
+
* @param {string} textPrefix
|
|
85
|
+
* @param {string} symbolPrefix
|
|
86
|
+
*/
|
|
87
|
+
private _finish;
|
|
88
|
+
}
|
|
89
|
+
export type SpinnerOptions = {
|
|
90
|
+
/**
|
|
91
|
+
* - Initial loading text
|
|
92
|
+
*/
|
|
93
|
+
message?: string | undefined;
|
|
94
|
+
/**
|
|
95
|
+
* - Defaults to process.stderr
|
|
96
|
+
*/
|
|
97
|
+
stream?: NodeJS.WritableStream | undefined;
|
|
98
|
+
/**
|
|
99
|
+
* - Color of the spinner glyph
|
|
100
|
+
*/
|
|
101
|
+
color?: string | undefined;
|
|
102
|
+
/**
|
|
103
|
+
* - Force accessible static mode
|
|
104
|
+
*/
|
|
105
|
+
accessible?: boolean | undefined;
|
|
106
|
+
};
|
|
107
|
+
import { OutputCoordinator } from '../../engine/renderer/coordinator.js';
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @template T
|
|
3
|
+
* @typedef {Object} PromptContext
|
|
4
|
+
* @property {string} message - Prompt label
|
|
5
|
+
* @property {T} [default] - Fallback value
|
|
6
|
+
* @property {(val: T) => boolean | string | Promise<boolean | string>} [validate]
|
|
7
|
+
* @property {NodeJS.ReadableStream} [input]
|
|
8
|
+
* @property {NodeJS.WritableStream} [output]
|
|
9
|
+
* @property {AbortSignal} [signal]
|
|
10
|
+
* @property {boolean} [accessible]
|
|
11
|
+
* @property {'throw' | 'return-null'} [onCancel]
|
|
12
|
+
* @property {Partial<import('../../core/caps/detect.js').TerminalCapabilities>} [capabilities]
|
|
13
|
+
*/
|
|
14
|
+
/**
|
|
15
|
+
* Run an interactive prompt with guaranteed terminal restoration and non-interactive fallbacks.
|
|
16
|
+
*
|
|
17
|
+
* @template T
|
|
18
|
+
* @param {Object} options
|
|
19
|
+
* @param {string} options.name - Prompt identifier (e.g. 'confirm', 'input')
|
|
20
|
+
* @param {PromptContext<T>} options.context - User supplied options
|
|
21
|
+
* @param {(state: any, caps: any) => string[]} options.renderView - View generator returning virtual lines
|
|
22
|
+
* @param {(key: import('../../engine/keyboard/parser.js').KeyEvent, state: any) => 'submit' | 'cancel' | 'update' | void} options.onKey - Key handler
|
|
23
|
+
* @param {any} options.initialState - Initial component state
|
|
24
|
+
* @param {(state: any) => T} options.getValue - Function extracting current value from state
|
|
25
|
+
* @param {(value: T, state: any) => string} [options.formatSubmitted] - Function formatting final submitted line
|
|
26
|
+
* @returns {Promise<T | null>}
|
|
27
|
+
*/
|
|
28
|
+
export function runPrompt<T>({ name, context, renderView, onKey, initialState, getValue, formatSubmitted }: {
|
|
29
|
+
name: string;
|
|
30
|
+
context: PromptContext<T>;
|
|
31
|
+
renderView: (state: any, caps: any) => string[];
|
|
32
|
+
onKey: (key: import("../../engine/keyboard/parser.js").KeyEvent, state: any) => "submit" | "cancel" | "update" | void;
|
|
33
|
+
initialState: any;
|
|
34
|
+
getValue: (state: any) => T;
|
|
35
|
+
formatSubmitted?: ((value: T, state: any) => string) | undefined;
|
|
36
|
+
}): Promise<T | null>;
|
|
37
|
+
export type PromptContext<T> = {
|
|
38
|
+
/**
|
|
39
|
+
* - Prompt label
|
|
40
|
+
*/
|
|
41
|
+
message: string;
|
|
42
|
+
/**
|
|
43
|
+
* - Fallback value
|
|
44
|
+
*/
|
|
45
|
+
default?: T | undefined;
|
|
46
|
+
validate?: ((val: T) => boolean | string | Promise<boolean | string>) | undefined;
|
|
47
|
+
input?: NodeJS.ReadableStream | undefined;
|
|
48
|
+
output?: NodeJS.WritableStream | undefined;
|
|
49
|
+
signal?: AbortSignal | undefined;
|
|
50
|
+
accessible?: boolean | undefined;
|
|
51
|
+
onCancel?: "throw" | "return-null" | undefined;
|
|
52
|
+
capabilities?: Partial<import("../../core/caps/detect.js").TerminalCapabilities> | undefined;
|
|
53
|
+
};
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @typedef {Object} ConfirmOptions
|
|
3
|
+
* @property {string} message - Prompt label
|
|
4
|
+
* @property {boolean} [default=true] - Default value
|
|
5
|
+
* @property {string} [activeText='Yes'] - Label for true
|
|
6
|
+
* @property {string} [inactiveText='No'] - Label for false
|
|
7
|
+
* @property {NodeJS.ReadableStream} [input]
|
|
8
|
+
* @property {NodeJS.WritableStream} [output]
|
|
9
|
+
* @property {AbortSignal} [signal]
|
|
10
|
+
* @property {boolean} [accessible]
|
|
11
|
+
* @property {'throw' | 'return-null'} [onCancel]
|
|
12
|
+
* @property {Partial<import('../../core/caps/detect.js').TerminalCapabilities>} [capabilities]
|
|
13
|
+
*/
|
|
14
|
+
/**
|
|
15
|
+
* Ask for a boolean confirmation (Y/n).
|
|
16
|
+
* @template {'throw' | 'return-null'} [TCancel='throw']
|
|
17
|
+
* @param {ConfirmOptions & { onCancel?: TCancel }} options
|
|
18
|
+
* @returns {Promise<TCancel extends 'return-null' ? boolean | null : boolean>}
|
|
19
|
+
*/
|
|
20
|
+
export function confirm<TCancel extends "throw" | "return-null" = "throw">(options: ConfirmOptions & {
|
|
21
|
+
onCancel?: TCancel;
|
|
22
|
+
}): Promise<TCancel extends "return-null" ? boolean | null : boolean>;
|
|
23
|
+
export type ConfirmOptions = {
|
|
24
|
+
/**
|
|
25
|
+
* - Prompt label
|
|
26
|
+
*/
|
|
27
|
+
message: string;
|
|
28
|
+
/**
|
|
29
|
+
* - Default value
|
|
30
|
+
*/
|
|
31
|
+
default?: boolean | undefined;
|
|
32
|
+
/**
|
|
33
|
+
* - Label for true
|
|
34
|
+
*/
|
|
35
|
+
activeText?: string | undefined;
|
|
36
|
+
/**
|
|
37
|
+
* - Label for false
|
|
38
|
+
*/
|
|
39
|
+
inactiveText?: string | undefined;
|
|
40
|
+
input?: NodeJS.ReadableStream | undefined;
|
|
41
|
+
output?: NodeJS.WritableStream | undefined;
|
|
42
|
+
signal?: AbortSignal | undefined;
|
|
43
|
+
accessible?: boolean | undefined;
|
|
44
|
+
onCancel?: "throw" | "return-null" | undefined;
|
|
45
|
+
capabilities?: Partial<import("../../core/caps/detect.js").TerminalCapabilities> | undefined;
|
|
46
|
+
};
|