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,46 @@
1
+ /**
2
+ * @typedef {Object} InputOptions
3
+ * @property {string} message - Prompt label
4
+ * @property {string} [default] - Fallback value
5
+ * @property {string} [placeholder] - Placeholder text
6
+ * @property {string} [initial] - Initial input buffer
7
+ * @property {(value: string) => boolean | string | Promise<boolean | string>} [validate]
8
+ * @property {NodeJS.ReadableStream} [input]
9
+ * @property {NodeJS.WritableStream} [output]
10
+ * @property {AbortSignal} [signal]
11
+ * @property {boolean} [accessible]
12
+ * @property {'throw' | 'return-null'} [onCancel]
13
+ */
14
+ /**
15
+ * Prompt user for a text string.
16
+ * @template {'throw' | 'return-null'} [TCancel='throw']
17
+ * @param {InputOptions & { onCancel?: TCancel }} options
18
+ * @returns {Promise<TCancel extends 'return-null' ? string | null : string>}
19
+ */
20
+ export function input<TCancel extends "throw" | "return-null" = "throw">(options: InputOptions & {
21
+ onCancel?: TCancel;
22
+ }): Promise<TCancel extends "return-null" ? string | null : string>;
23
+ export type InputOptions = {
24
+ /**
25
+ * - Prompt label
26
+ */
27
+ message: string;
28
+ /**
29
+ * - Fallback value
30
+ */
31
+ default?: string | undefined;
32
+ /**
33
+ * - Placeholder text
34
+ */
35
+ placeholder?: string | undefined;
36
+ /**
37
+ * - Initial input buffer
38
+ */
39
+ initial?: string | undefined;
40
+ validate?: ((value: string) => boolean | string | Promise<boolean | string>) | undefined;
41
+ input?: NodeJS.ReadableStream | undefined;
42
+ output?: NodeJS.WritableStream | undefined;
43
+ signal?: AbortSignal | undefined;
44
+ accessible?: boolean | undefined;
45
+ onCancel?: "throw" | "return-null" | undefined;
46
+ };
@@ -0,0 +1,100 @@
1
+ /**
2
+ * @template [T=any]
3
+ * @typedef {Object} MultiSelectItem
4
+ * @property {string} label - Display label
5
+ * @property {T} value - Selected value
6
+ * @property {string} [hint] - Optional muted hint
7
+ * @property {boolean | string} [disabled] - Whether item is disabled
8
+ * @property {boolean} [selected] - Initially selected
9
+ */
10
+ /**
11
+ * @template [T=any]
12
+ * @typedef {Object} MultiSelectOptions
13
+ * @property {string} message - Prompt label
14
+ * @property {readonly MultiSelectItem<T>[] | readonly { readonly label: string; readonly value: T; readonly hint?: string; readonly disabled?: boolean | string; readonly selected?: boolean }[]} items - List of choices
15
+ * @property {T[]} [default] - Default selected values
16
+ * @property {number} [pageSize=7] - Number of items displayed at once
17
+ * @property {boolean} [required=false] - At least one item required
18
+ * @property {number} [min] - Minimum selection count
19
+ * @property {number} [max] - Maximum selection count
20
+ * @property {NodeJS.ReadableStream} [input]
21
+ * @property {NodeJS.WritableStream} [output]
22
+ * @property {AbortSignal} [signal]
23
+ * @property {boolean} [accessible]
24
+ * @property {'throw' | 'return-null'} [onCancel]
25
+ * @property {Partial<import('../../core/caps/detect.js').TerminalCapabilities>} [capabilities]
26
+ */
27
+ /**
28
+ * Multiple item checkbox select prompt.
29
+ * @template T
30
+ * @template {'throw' | 'return-null'} [TCancel='throw']
31
+ * @param {MultiSelectOptions<T> & { onCancel?: TCancel }} options
32
+ * @returns {Promise<TCancel extends 'return-null' ? T[] | null : T[]>}
33
+ */
34
+ export function multiselect<T, TCancel extends "throw" | "return-null" = "throw">(options: MultiSelectOptions<T> & {
35
+ onCancel?: TCancel;
36
+ }): Promise<TCancel extends "return-null" ? T[] | null : T[]>;
37
+ export type MultiSelectItem<T = any> = {
38
+ /**
39
+ * - Display label
40
+ */
41
+ label: string;
42
+ /**
43
+ * - Selected value
44
+ */
45
+ value: T;
46
+ /**
47
+ * - Optional muted hint
48
+ */
49
+ hint?: string | undefined;
50
+ /**
51
+ * - Whether item is disabled
52
+ */
53
+ disabled?: string | boolean | undefined;
54
+ /**
55
+ * - Initially selected
56
+ */
57
+ selected?: boolean | undefined;
58
+ };
59
+ export type MultiSelectOptions<T = any> = {
60
+ /**
61
+ * - Prompt label
62
+ */
63
+ message: string;
64
+ /**
65
+ * - List of choices
66
+ */
67
+ items: readonly MultiSelectItem<T>[] | readonly {
68
+ readonly label: string;
69
+ readonly value: T;
70
+ readonly hint?: string;
71
+ readonly disabled?: boolean | string;
72
+ readonly selected?: boolean;
73
+ }[];
74
+ /**
75
+ * - Default selected values
76
+ */
77
+ default?: T[] | undefined;
78
+ /**
79
+ * - Number of items displayed at once
80
+ */
81
+ pageSize?: number | undefined;
82
+ /**
83
+ * - At least one item required
84
+ */
85
+ required?: boolean | undefined;
86
+ /**
87
+ * - Minimum selection count
88
+ */
89
+ min?: number | undefined;
90
+ /**
91
+ * - Maximum selection count
92
+ */
93
+ max?: number | undefined;
94
+ input?: NodeJS.ReadableStream | undefined;
95
+ output?: NodeJS.WritableStream | undefined;
96
+ signal?: AbortSignal | undefined;
97
+ accessible?: boolean | undefined;
98
+ onCancel?: "throw" | "return-null" | undefined;
99
+ capabilities?: Partial<import("../../core/caps/detect.js").TerminalCapabilities> | undefined;
100
+ };
@@ -0,0 +1,58 @@
1
+ /**
2
+ * @typedef {Object} NumberOptions
3
+ * @property {string} message - Prompt label
4
+ * @property {number} [default] - Default number value
5
+ * @property {number} [min] - Minimum allowed value
6
+ * @property {number} [max] - Maximum allowed value
7
+ * @property {number} [step=1] - Increment/decrement step
8
+ * @property {boolean} [float=false] - Whether decimal numbers are allowed
9
+ * @property {(value: number) => boolean | string | Promise<boolean | string>} [validate]
10
+ * @property {NodeJS.ReadableStream} [input]
11
+ * @property {NodeJS.WritableStream} [output]
12
+ * @property {AbortSignal} [signal]
13
+ * @property {boolean} [accessible]
14
+ * @property {'throw' | 'return-null'} [onCancel]
15
+ * @property {Partial<import('../../core/caps/detect.js').TerminalCapabilities>} [capabilities]
16
+ */
17
+ /**
18
+ * Prompt user for a numeric value with bounds checking and keyboard stepping.
19
+ * @template {'throw' | 'return-null'} [TCancel='throw']
20
+ * @param {NumberOptions & { onCancel?: TCancel }} options
21
+ * @returns {Promise<TCancel extends 'return-null' ? number | null : number>}
22
+ */
23
+ export function number<TCancel extends "throw" | "return-null" = "throw">(options: NumberOptions & {
24
+ onCancel?: TCancel;
25
+ }): Promise<TCancel extends "return-null" ? number | null : number>;
26
+ export type NumberOptions = {
27
+ /**
28
+ * - Prompt label
29
+ */
30
+ message: string;
31
+ /**
32
+ * - Default number value
33
+ */
34
+ default?: number | undefined;
35
+ /**
36
+ * - Minimum allowed value
37
+ */
38
+ min?: number | undefined;
39
+ /**
40
+ * - Maximum allowed value
41
+ */
42
+ max?: number | undefined;
43
+ /**
44
+ * - Increment/decrement step
45
+ */
46
+ step?: number | undefined;
47
+ /**
48
+ * - Whether decimal numbers are allowed
49
+ */
50
+ float?: boolean | undefined;
51
+ validate?: ((value: number) => boolean | string | Promise<boolean | string>) | undefined;
52
+ input?: NodeJS.ReadableStream | undefined;
53
+ output?: NodeJS.WritableStream | undefined;
54
+ signal?: AbortSignal | undefined;
55
+ accessible?: boolean | undefined;
56
+ onCancel?: "throw" | "return-null" | undefined;
57
+ capabilities?: Partial<import("../../core/caps/detect.js").TerminalCapabilities> | undefined;
58
+ };
@@ -0,0 +1,45 @@
1
+ /**
2
+ * @typedef {Object} PasswordOptions
3
+ * @property {string} message - Prompt label
4
+ * @property {string} [default] - Fallback value
5
+ * @property {string} [mask='*'] - Mask character
6
+ * @property {(value: string) => 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
+ * Prompt user for a secret password.
16
+ * Never leaks the secret value in logs, errors, or snapshots.
17
+ *
18
+ * @template {'throw' | 'return-null'} [TCancel='throw']
19
+ * @param {PasswordOptions & { onCancel?: TCancel }} options
20
+ * @returns {Promise<TCancel extends 'return-null' ? string | null : string>}
21
+ */
22
+ export function password<TCancel extends "throw" | "return-null" = "throw">(options: PasswordOptions & {
23
+ onCancel?: TCancel;
24
+ }): Promise<TCancel extends "return-null" ? string | null : string>;
25
+ export type PasswordOptions = {
26
+ /**
27
+ * - Prompt label
28
+ */
29
+ message: string;
30
+ /**
31
+ * - Fallback value
32
+ */
33
+ default?: string | undefined;
34
+ /**
35
+ * - Mask character
36
+ */
37
+ mask?: string | undefined;
38
+ validate?: ((value: string) => boolean | string | Promise<boolean | string>) | undefined;
39
+ input?: NodeJS.ReadableStream | undefined;
40
+ output?: NodeJS.WritableStream | undefined;
41
+ signal?: AbortSignal | undefined;
42
+ accessible?: boolean | undefined;
43
+ onCancel?: "throw" | "return-null" | undefined;
44
+ capabilities?: Partial<import("../../core/caps/detect.js").TerminalCapabilities> | undefined;
45
+ };
@@ -0,0 +1,84 @@
1
+ /**
2
+ * @template [T=any]
3
+ * @typedef {Object} SelectItem
4
+ * @property {string} label - Display label
5
+ * @property {T} value - Selected value
6
+ * @property {string} [hint] - Optional muted hint
7
+ * @property {boolean | string} [disabled] - Whether item is disabled
8
+ */
9
+ /**
10
+ * @template [T=any]
11
+ * @typedef {Object} SelectOptions
12
+ * @property {string} message - Prompt label
13
+ * @property {readonly SelectItem<T>[] | readonly { readonly label: string; readonly value: T; readonly hint?: string; readonly disabled?: boolean | string }[]} items - List of choices
14
+ * @property {T} [default] - Default selected value
15
+ * @property {number} [pageSize=7] - Number of items displayed at once
16
+ * @property {boolean} [loop=true] - Loop navigation
17
+ * @property {NodeJS.ReadableStream} [input]
18
+ * @property {NodeJS.WritableStream} [output]
19
+ * @property {AbortSignal} [signal]
20
+ * @property {boolean} [accessible]
21
+ * @property {'throw' | 'return-null'} [onCancel]
22
+ * @property {Partial<import('../../core/caps/detect.js').TerminalCapabilities>} [capabilities]
23
+ */
24
+ /**
25
+ * Single item select prompt with arrow navigation.
26
+ * @template T
27
+ * @template {'throw' | 'return-null'} [TCancel='throw']
28
+ * @param {SelectOptions<T> & { onCancel?: TCancel }} options
29
+ * @returns {Promise<TCancel extends 'return-null' ? T | null : T>}
30
+ */
31
+ export function select<T, TCancel extends "throw" | "return-null" = "throw">(options: SelectOptions<T> & {
32
+ onCancel?: TCancel;
33
+ }): Promise<TCancel extends "return-null" ? T | null : T>;
34
+ export type SelectItem<T = any> = {
35
+ /**
36
+ * - Display label
37
+ */
38
+ label: string;
39
+ /**
40
+ * - Selected value
41
+ */
42
+ value: T;
43
+ /**
44
+ * - Optional muted hint
45
+ */
46
+ hint?: string | undefined;
47
+ /**
48
+ * - Whether item is disabled
49
+ */
50
+ disabled?: string | boolean | undefined;
51
+ };
52
+ export type SelectOptions<T = any> = {
53
+ /**
54
+ * - Prompt label
55
+ */
56
+ message: string;
57
+ /**
58
+ * - List of choices
59
+ */
60
+ items: readonly SelectItem<T>[] | readonly {
61
+ readonly label: string;
62
+ readonly value: T;
63
+ readonly hint?: string;
64
+ readonly disabled?: boolean | string;
65
+ }[];
66
+ /**
67
+ * - Default selected value
68
+ */
69
+ default?: T | undefined;
70
+ /**
71
+ * - Number of items displayed at once
72
+ */
73
+ pageSize?: number | undefined;
74
+ /**
75
+ * - Loop navigation
76
+ */
77
+ loop?: boolean | undefined;
78
+ input?: NodeJS.ReadableStream | undefined;
79
+ output?: NodeJS.WritableStream | undefined;
80
+ signal?: AbortSignal | undefined;
81
+ accessible?: boolean | undefined;
82
+ onCancel?: "throw" | "return-null" | undefined;
83
+ capabilities?: Partial<import("../../core/caps/detect.js").TerminalCapabilities> | undefined;
84
+ };
@@ -0,0 +1,154 @@
1
+ export namespace SGR {
2
+ let reset: string;
3
+ namespace bold {
4
+ let open: string;
5
+ let close: string;
6
+ }
7
+ namespace dim {
8
+ let open_1: string;
9
+ export { open_1 as open };
10
+ let close_1: string;
11
+ export { close_1 as close };
12
+ }
13
+ namespace italic {
14
+ let open_2: string;
15
+ export { open_2 as open };
16
+ let close_2: string;
17
+ export { close_2 as close };
18
+ }
19
+ namespace underline {
20
+ let open_3: string;
21
+ export { open_3 as open };
22
+ let close_3: string;
23
+ export { close_3 as close };
24
+ }
25
+ namespace inverse {
26
+ let open_4: string;
27
+ export { open_4 as open };
28
+ let close_4: string;
29
+ export { close_4 as close };
30
+ }
31
+ namespace strikethrough {
32
+ let open_5: string;
33
+ export { open_5 as open };
34
+ let close_5: string;
35
+ export { close_5 as close };
36
+ }
37
+ namespace black {
38
+ let open_6: string;
39
+ export { open_6 as open };
40
+ let close_6: string;
41
+ export { close_6 as close };
42
+ }
43
+ namespace red {
44
+ let open_7: string;
45
+ export { open_7 as open };
46
+ let close_7: string;
47
+ export { close_7 as close };
48
+ }
49
+ namespace green {
50
+ let open_8: string;
51
+ export { open_8 as open };
52
+ let close_8: string;
53
+ export { close_8 as close };
54
+ }
55
+ namespace yellow {
56
+ let open_9: string;
57
+ export { open_9 as open };
58
+ let close_9: string;
59
+ export { close_9 as close };
60
+ }
61
+ namespace blue {
62
+ let open_10: string;
63
+ export { open_10 as open };
64
+ let close_10: string;
65
+ export { close_10 as close };
66
+ }
67
+ namespace magenta {
68
+ let open_11: string;
69
+ export { open_11 as open };
70
+ let close_11: string;
71
+ export { close_11 as close };
72
+ }
73
+ namespace cyan {
74
+ let open_12: string;
75
+ export { open_12 as open };
76
+ let close_12: string;
77
+ export { close_12 as close };
78
+ }
79
+ namespace white {
80
+ let open_13: string;
81
+ export { open_13 as open };
82
+ let close_13: string;
83
+ export { close_13 as close };
84
+ }
85
+ namespace gray {
86
+ let open_14: string;
87
+ export { open_14 as open };
88
+ let close_14: string;
89
+ export { close_14 as close };
90
+ }
91
+ namespace bgBlack {
92
+ let open_15: string;
93
+ export { open_15 as open };
94
+ let close_15: string;
95
+ export { close_15 as close };
96
+ }
97
+ namespace bgRed {
98
+ let open_16: string;
99
+ export { open_16 as open };
100
+ let close_16: string;
101
+ export { close_16 as close };
102
+ }
103
+ namespace bgGreen {
104
+ let open_17: string;
105
+ export { open_17 as open };
106
+ let close_17: string;
107
+ export { close_17 as close };
108
+ }
109
+ namespace bgYellow {
110
+ let open_18: string;
111
+ export { open_18 as open };
112
+ let close_18: string;
113
+ export { close_18 as close };
114
+ }
115
+ namespace bgBlue {
116
+ let open_19: string;
117
+ export { open_19 as open };
118
+ let close_19: string;
119
+ export { close_19 as close };
120
+ }
121
+ namespace bgMagenta {
122
+ let open_20: string;
123
+ export { open_20 as open };
124
+ let close_20: string;
125
+ export { close_20 as close };
126
+ }
127
+ namespace bgCyan {
128
+ let open_21: string;
129
+ export { open_21 as open };
130
+ let close_21: string;
131
+ export { close_21 as close };
132
+ }
133
+ namespace bgWhite {
134
+ let open_22: string;
135
+ export { open_22 as open };
136
+ let close_22: string;
137
+ export { close_22 as close };
138
+ }
139
+ }
140
+ export namespace CURSOR {
141
+ let hide: string;
142
+ let show: string;
143
+ let save: string;
144
+ let restore: string;
145
+ function up(n?: number): string;
146
+ function down(n?: number): string;
147
+ function forward(n?: number): string;
148
+ function back(n?: number): string;
149
+ function toColumn(n?: number): string;
150
+ let clearLine: string;
151
+ let clearLineToEnd: string;
152
+ let clearLineToStart: string;
153
+ let clearDown: string;
154
+ }
@@ -0,0 +1,74 @@
1
+ /**
2
+ * @fileoverview Terminal capability detection (color depth, Unicode, TTY, CI, NO_COLOR, FORCE_COLOR).
3
+ */
4
+ /**
5
+ * @typedef {Object} TerminalCapabilities
6
+ * @property {number} colorLevel - 0 (none), 1 (16 colors), 2 (256 colors), 3 (16M truecolor)
7
+ * @property {boolean} hasColor - Whether basic colors are supported
8
+ * @property {boolean} has256 - Whether 256 colors are supported
9
+ * @property {boolean} hasTrueColor - Whether 24-bit TrueColor is supported
10
+ * @property {boolean} unicode - Whether UTF-8 / Unicode characters are supported
11
+ * @property {boolean} isTTY - Whether the stream is an interactive terminal
12
+ * @property {boolean} isCI - Whether running in a CI environment
13
+ * @property {boolean} isDumb - Whether the terminal is TERM=dumb
14
+ * @property {number} columns - Viewport columns width
15
+ * @property {number} rows - Viewport rows height
16
+ * @property {boolean} reducedMotion - Whether animations should be suppressed
17
+ */
18
+ /**
19
+ * Detect capabilities of a given output stream and environment.
20
+ * @param {Object} [options]
21
+ * @param {NodeJS.WritableStream} [options.stream] - Defaults to process.stderr
22
+ * @param {Record<string, string | undefined>} [options.env] - Defaults to process.env
23
+ * @returns {TerminalCapabilities}
24
+ */
25
+ export function detectCapabilities(options?: {
26
+ stream?: NodeJS.WritableStream | undefined;
27
+ env?: Record<string, string | undefined> | undefined;
28
+ }): TerminalCapabilities;
29
+ export type TerminalCapabilities = {
30
+ /**
31
+ * - 0 (none), 1 (16 colors), 2 (256 colors), 3 (16M truecolor)
32
+ */
33
+ colorLevel: number;
34
+ /**
35
+ * - Whether basic colors are supported
36
+ */
37
+ hasColor: boolean;
38
+ /**
39
+ * - Whether 256 colors are supported
40
+ */
41
+ has256: boolean;
42
+ /**
43
+ * - Whether 24-bit TrueColor is supported
44
+ */
45
+ hasTrueColor: boolean;
46
+ /**
47
+ * - Whether UTF-8 / Unicode characters are supported
48
+ */
49
+ unicode: boolean;
50
+ /**
51
+ * - Whether the stream is an interactive terminal
52
+ */
53
+ isTTY: boolean;
54
+ /**
55
+ * - Whether running in a CI environment
56
+ */
57
+ isCI: boolean;
58
+ /**
59
+ * - Whether the terminal is TERM=dumb
60
+ */
61
+ isDumb: boolean;
62
+ /**
63
+ * - Viewport columns width
64
+ */
65
+ columns: number;
66
+ /**
67
+ * - Viewport rows height
68
+ */
69
+ rows: number;
70
+ /**
71
+ * - Whether animations should be suppressed
72
+ */
73
+ reducedMotion: boolean;
74
+ };
@@ -0,0 +1,73 @@
1
+ /**
2
+ * @fileoverview Structured error hierarchy and stable error codes for TermKit.
3
+ */
4
+ /**
5
+ * Base error class for all TermKit errors.
6
+ */
7
+ export class TermKitError extends Error {
8
+ /**
9
+ * @param {string} message
10
+ * @param {string} [code='ERR_TERMKIT']
11
+ */
12
+ constructor(message: string, code?: string);
13
+ /** @type {string} */
14
+ code: string;
15
+ }
16
+ /**
17
+ * Thrown when an interactive prompt or operation is cancelled by the user or signal.
18
+ */
19
+ export class CancelError extends TermKitError {
20
+ /**
21
+ * @param {string} [message]
22
+ * @param {'ctrl-c' | 'escape' | 'stream-closed' | 'abort'} [reason='ctrl-c']
23
+ */
24
+ constructor(message?: string, reason?: "ctrl-c" | "escape" | "stream-closed" | "abort");
25
+ /** @type {'ctrl-c' | 'escape' | 'stream-closed' | 'abort'} */
26
+ reason: "ctrl-c" | "escape" | "stream-closed" | "abort";
27
+ }
28
+ /**
29
+ * Thrown when a prompt is invoked in a non-interactive environment without a default value.
30
+ */
31
+ export class NonInteractiveError extends TermKitError {
32
+ /** @type {string} */
33
+ promptName: string;
34
+ }
35
+ /**
36
+ * Thrown or reported when prompt validation fails.
37
+ * Guarantees that secret inputs are never echoed in error messages.
38
+ */
39
+ export class ValidationError extends TermKitError {
40
+ /**
41
+ * @param {string} promptName
42
+ * @param {string} validationMessage
43
+ * @param {boolean} [isSecret=false]
44
+ */
45
+ constructor(promptName: string, validationMessage: string, isSecret?: boolean);
46
+ /** @type {string} */
47
+ promptName: string;
48
+ /** @type {boolean} */
49
+ isSecret: boolean;
50
+ }
51
+ /**
52
+ * Thrown when invalid configuration options are supplied to a component.
53
+ */
54
+ export class ConfigurationError extends TermKitError {
55
+ /**
56
+ * @param {string} optionName
57
+ * @param {string} detail
58
+ */
59
+ constructor(optionName: string, detail: string);
60
+ /** @type {string} */
61
+ optionName: string;
62
+ }
63
+ /**
64
+ * Thrown when the target stream ends unexpectedly during an active component.
65
+ */
66
+ export class StreamClosedError extends TermKitError {
67
+ /**
68
+ * @param {'stdin' | 'stdout' | 'stderr'} stream
69
+ */
70
+ constructor(stream: "stdin" | "stdout" | "stderr");
71
+ /** @type {'stdin' | 'stdout' | 'stderr'} */
72
+ stream: "stdin" | "stdout" | "stderr";
73
+ }
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Creates a nesting-safe styling instance with a specified color depth level.
3
+ * @param {Object} [options]
4
+ * @param {number} [options.colorLevel] - 0 (none), 1 (16), 2 (256), 3 (TrueColor)
5
+ */
6
+ export function createStyleEngine(options?: {
7
+ colorLevel?: number | undefined;
8
+ }): any;
9
+ /** Global default style function automatically configured by detected capabilities */
10
+ export const style: any;
11
+ export const colors: any;
12
+ export * from "../width/string-width.js";
@@ -0,0 +1,42 @@
1
+ /**
2
+ * Remove all ANSI escape codes from a string.
3
+ * @param {string} str
4
+ * @returns {string}
5
+ */
6
+ export function stripAnsi(str: string): string;
7
+ /**
8
+ * Calculate the visual column width of a string in a terminal.
9
+ * Correctly strips ANSI escape codes and accounts for emojis, ZWJ sequences,
10
+ * East Asian characters, combining diacritics, and zero-width codes.
11
+ *
12
+ * @param {string} str
13
+ * @returns {number}
14
+ */
15
+ export function stringWidth(str: string): number;
16
+ /**
17
+ * Truncate a string to a maximum visual column width, appending an optional ellipsis.
18
+ * Preserves ANSI styling codes.
19
+ *
20
+ * @param {string} str
21
+ * @param {number} maxWidth
22
+ * @param {string} [ellipsis]
23
+ * @returns {string}
24
+ */
25
+ export function truncate(str: string, maxWidth: number, ellipsis?: string): string;
26
+ /**
27
+ * Wrap text cleanly to fit within maxWidth columns.
28
+ *
29
+ * @param {string} str
30
+ * @param {number} maxWidth
31
+ * @returns {string[]}
32
+ */
33
+ export function wrapText(str: string, maxWidth: number): string[];
34
+ /**
35
+ * Calculate the visual column width of a string in a terminal.
36
+ * Correctly strips ANSI escape codes and accounts for emojis, ZWJ sequences,
37
+ * East Asian characters, combining diacritics, and zero-width codes.
38
+ *
39
+ * @param {string} str
40
+ * @returns {number}
41
+ */
42
+ export function visibleLength(str: string): number;