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
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
- # Temporary Holding Version
1
+ # TermKit
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > Zero-dependency, cohesive TypeScript/ESM toolkit for building robust Node.js CLI user interfaces.
4
+
5
+ [![CI](https://github.com/hexqbv/TermKit/actions/workflows/ci.yml/badge.svg)](https://github.com/hexqbv/TermKit/actions/workflows/ci.yml)
6
+ [![Node >= 22.0](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org)
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
8
+ [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-success.svg)](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,2 @@
1
+ export * from "./spinner.js";
2
+ export * from "./progressBar.js";
@@ -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
+ };
@@ -0,0 +1,6 @@
1
+ export * from "./confirm.js";
2
+ export * from "./input.js";
3
+ export * from "./password.js";
4
+ export * from "./number.js";
5
+ export * from "./select.js";
6
+ export * from "./multiselect.js";