@voidzero-dev/vite-plus-prompts 1.0.0 → 1.2.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/README.md +58 -0
- package/dist/index.d.mts +134 -23
- package/dist/index.mjs +589 -510
- package/package.json +3 -3
package/README.md
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# @voidzero-dev/vite-plus-prompts
|
|
2
|
+
|
|
3
|
+
Terminal prompts shared by Vite+ and tools that use its visual identity.
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
import { isCancel, log, note, select } from '@voidzero-dev/vite-plus-prompts';
|
|
7
|
+
|
|
8
|
+
const framework = await select({
|
|
9
|
+
message: 'Choose a framework:',
|
|
10
|
+
options: [
|
|
11
|
+
{ value: 'react', label: 'React', hint: 'TSX Pages' },
|
|
12
|
+
{ value: 'vue', label: 'Vue', hint: 'Vue SFC Pages' },
|
|
13
|
+
],
|
|
14
|
+
});
|
|
15
|
+
|
|
16
|
+
if (!isCancel(framework)) {
|
|
17
|
+
log.success(`Selected ${framework}`);
|
|
18
|
+
note('Run vp dev to start developing.', 'Next steps');
|
|
19
|
+
}
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Blue `›` pointers identify focused choices and active prompts. Completed steps
|
|
23
|
+
and rounded box borders use gray; warnings use yellow and errors use red.
|
|
24
|
+
Inactive choices are dimmed, and descriptive hints appear on the focused choice.
|
|
25
|
+
Logs retain severity symbols without guide bars and use compact spacing.
|
|
26
|
+
Notes have complete borders and readable content by default.
|
|
27
|
+
|
|
28
|
+
Guides are off by default. Pass `withGuide: true` for one call, or use
|
|
29
|
+
`updateSettings({ withGuide: true })` to enable them globally. This controls the
|
|
30
|
+
prompt gutter, not box borders. Logs accept `spacing` for explicit blank rows;
|
|
31
|
+
notes accept `format` and boxes accept `formatBorder` and `rounded`.
|
|
32
|
+
|
|
33
|
+
Select and multiselect prompts show compact keyboard instructions. Pass
|
|
34
|
+
`showInstructions: false` to hide them. Text, password, path, and autocomplete
|
|
35
|
+
validation supports synchronous or asynchronous functions and Standard Schema.
|
|
36
|
+
Passwords accept a placeholder and always mask entered values. Path prompts
|
|
37
|
+
support directory navigation and Tab completion; general autocomplete can opt
|
|
38
|
+
in with `completeOnTab: true`.
|
|
39
|
+
|
|
40
|
+
`accessible: true`, `updateSettings({ accessible: true })`, or `ACCESSIBLE=1`
|
|
41
|
+
enables static prompt output for screen readers. Spinners use static output in
|
|
42
|
+
accessible mode, CI, and non-TTY streams. Their `pause()` and `resume()` methods
|
|
43
|
+
preserve elapsed time while excluding pauses. `CANCEL_SYMBOL` is exported for
|
|
44
|
+
callers that need the exact cancellation sentinel; `isCancel()` narrows results.
|
|
45
|
+
|
|
46
|
+
The interaction engine is `@clack/core` 1.5.1 or newer. Rendering and the shared
|
|
47
|
+
visual defaults are maintained in this package, so consumers can use the same
|
|
48
|
+
appearance without implementing their own prompt renderers.
|
|
49
|
+
|
|
50
|
+
## Verification
|
|
51
|
+
|
|
52
|
+
From the repository root:
|
|
53
|
+
|
|
54
|
+
```sh
|
|
55
|
+
vp check packages/prompts/src
|
|
56
|
+
vp test run packages/prompts/src/__tests__
|
|
57
|
+
pnpm --filter @voidzero-dev/vite-plus-prompts build
|
|
58
|
+
```
|
package/dist/index.d.mts
CHANGED
|
@@ -1,6 +1,14 @@
|
|
|
1
|
-
import { AutocompletePrompt, ClackSettings, State, isCancel, settings, updateSettings } from "@clack/core";
|
|
1
|
+
import { AutocompletePrompt, CANCEL_SYMBOL, CANCEL_SYMBOL as CANCEL_SYMBOL$1, ClackSettings, State, Validate, isCancel, settings, updateSettings } from "@clack/core";
|
|
2
2
|
import { Readable, Writable } from "node:stream";
|
|
3
3
|
//#region src/common.d.ts
|
|
4
|
+
/** Wrap using visible columns rather than the length of ANSI escape sequences. */
|
|
5
|
+
export declare const wrapTextWithPrefix: (output: Writable | undefined, text: string, prefix: string, startPrefix?: string) => string;
|
|
6
|
+
export declare const getGuide: (opts?: CommonOptions) => boolean;
|
|
7
|
+
export declare const promptTitle: (message: string, state: State, opts: CommonOptions) => string;
|
|
8
|
+
export declare const optionText: (output: Writable | undefined, marker: string, label: string, format: (text: string) => string, suffix?: string) => string;
|
|
9
|
+
export declare const SELECT_INSTRUCTIONS: string[];
|
|
10
|
+
export declare const MULTISELECT_INSTRUCTIONS: string[];
|
|
11
|
+
export declare const formatInstructionFooter: (instructions: string[], hasGuide: boolean, output?: Writable) => string[];
|
|
4
12
|
export declare const unicode: boolean;
|
|
5
13
|
export declare const isCI: () => boolean;
|
|
6
14
|
export declare const isTTY: (output: Writable) => boolean;
|
|
@@ -40,6 +48,8 @@ export interface CommonOptions {
|
|
|
40
48
|
output?: Writable;
|
|
41
49
|
signal?: AbortSignal;
|
|
42
50
|
withGuide?: boolean;
|
|
51
|
+
/** Static output for screen readers; also respects settings and ACCESSIBLE. */
|
|
52
|
+
accessible?: boolean;
|
|
43
53
|
/**
|
|
44
54
|
* Stable identifier used in snapshot-test milestones
|
|
45
55
|
* (`<kind>:<testId>:<state>`). Only read when `VP_EMIT_MILESTONES=1`;
|
|
@@ -105,8 +115,10 @@ export interface SelectOptions<Value> extends CommonOptions {
|
|
|
105
115
|
options: Option<Value>[];
|
|
106
116
|
initialValue?: Value;
|
|
107
117
|
maxItems?: number;
|
|
118
|
+
/** Show keyboard instructions (default: true). */
|
|
119
|
+
showInstructions?: boolean;
|
|
108
120
|
}
|
|
109
|
-
export declare const select: <Value>(opts: SelectOptions<Value>) => Promise<Value |
|
|
121
|
+
export declare const select: <Value>(opts: SelectOptions<Value>) => Promise<Value | typeof CANCEL_SYMBOL$1>;
|
|
110
122
|
//#endregion
|
|
111
123
|
//#region src/autocomplete.d.ts
|
|
112
124
|
interface AutocompleteSharedOptions<Value> extends CommonOptions {
|
|
@@ -129,7 +141,7 @@ interface AutocompleteSharedOptions<Value> extends CommonOptions {
|
|
|
129
141
|
/**
|
|
130
142
|
* Validates the value
|
|
131
143
|
*/
|
|
132
|
-
validate?:
|
|
144
|
+
validate?: Validate<Value | Value[]>;
|
|
133
145
|
/**
|
|
134
146
|
* Custom filter function to match options against search input.
|
|
135
147
|
* If not provided, a default filter that matches label, hint, and value is used.
|
|
@@ -145,8 +157,10 @@ export interface AutocompleteOptions<Value> extends AutocompleteSharedOptions<Va
|
|
|
145
157
|
* The initial user input
|
|
146
158
|
*/
|
|
147
159
|
initialUserInput?: string;
|
|
160
|
+
/** Complete the focused suggestion on Tab (enabled by path). */
|
|
161
|
+
completeOnTab?: boolean;
|
|
148
162
|
}
|
|
149
|
-
export declare const autocomplete: <Value>(opts: AutocompleteOptions<Value>) => Promise<Value |
|
|
163
|
+
export declare const autocomplete: <Value>(opts: AutocompleteOptions<Value>) => Promise<Value | typeof CANCEL_SYMBOL$1>;
|
|
150
164
|
export interface AutocompleteMultiSelectOptions<Value> extends AutocompleteSharedOptions<Value> {
|
|
151
165
|
/**
|
|
152
166
|
* The initial selected values
|
|
@@ -160,7 +174,7 @@ export interface AutocompleteMultiSelectOptions<Value> extends AutocompleteShare
|
|
|
160
174
|
/**
|
|
161
175
|
* Integrated autocomplete multiselect - combines type-ahead filtering with multiselect in one UI
|
|
162
176
|
*/
|
|
163
|
-
export declare const autocompleteMultiselect: <Value>(opts: AutocompleteMultiSelectOptions<Value>) => Promise<Value[] |
|
|
177
|
+
export declare const autocompleteMultiselect: <Value>(opts: AutocompleteMultiSelectOptions<Value>) => Promise<Value[] | typeof CANCEL_SYMBOL$1>;
|
|
164
178
|
//#endregion
|
|
165
179
|
//#region src/box.d.ts
|
|
166
180
|
export type BoxAlignment = 'left' | 'center' | 'right';
|
|
@@ -183,7 +197,7 @@ export interface ConfirmOptions extends CommonOptions {
|
|
|
183
197
|
initialValue?: boolean;
|
|
184
198
|
vertical?: boolean;
|
|
185
199
|
}
|
|
186
|
-
export declare const confirm: (opts: ConfirmOptions) => Promise<boolean |
|
|
200
|
+
export declare const confirm: (opts: ConfirmOptions) => Promise<boolean | typeof CANCEL_SYMBOL$1>;
|
|
187
201
|
//#endregion
|
|
188
202
|
//#region src/group.d.ts
|
|
189
203
|
type Prettify<T> = { [P in keyof T]: T[P]; } & {};
|
|
@@ -215,19 +229,71 @@ export interface GroupMultiSelectOptions<Value> extends CommonOptions {
|
|
|
215
229
|
cursorAt?: Value;
|
|
216
230
|
selectableGroups?: boolean;
|
|
217
231
|
groupSpacing?: number;
|
|
232
|
+
maxItems?: number;
|
|
233
|
+
showInstructions?: boolean;
|
|
218
234
|
}
|
|
219
|
-
export declare const groupMultiselect: <Value>(opts: GroupMultiSelectOptions<Value>) => Promise<Value[] |
|
|
235
|
+
export declare const groupMultiselect: <Value>(opts: GroupMultiSelectOptions<Value>) => Promise<Value[] | typeof CANCEL_SYMBOL$1>;
|
|
220
236
|
//#endregion
|
|
221
237
|
//#region src/limit-options.d.ts
|
|
238
|
+
/**
|
|
239
|
+
* Options for the {@link limitOptions} function.
|
|
240
|
+
*/
|
|
222
241
|
export interface LimitOptionsParams<TOption> extends CommonOptions {
|
|
242
|
+
/**
|
|
243
|
+
* The list of options to display.
|
|
244
|
+
*/
|
|
223
245
|
options: TOption[];
|
|
224
|
-
|
|
246
|
+
/**
|
|
247
|
+
* The index of the currently active/selected option.
|
|
248
|
+
*/
|
|
225
249
|
cursor: number;
|
|
250
|
+
/**
|
|
251
|
+
* A function that styles the given option string.
|
|
252
|
+
*
|
|
253
|
+
* @param option - The option string to style.
|
|
254
|
+
* @param active - Whether the option is currently selected.
|
|
255
|
+
*/
|
|
226
256
|
style: (option: TOption, active: boolean) => string;
|
|
257
|
+
/**
|
|
258
|
+
* Maximum number of options to display at once.
|
|
259
|
+
* @default Infinity
|
|
260
|
+
*/
|
|
261
|
+
maxItems?: number;
|
|
262
|
+
/**
|
|
263
|
+
* Number of columns to reserve for padding.
|
|
264
|
+
* @default 0
|
|
265
|
+
*/
|
|
227
266
|
columnPadding?: number;
|
|
267
|
+
/**
|
|
268
|
+
* Number of rows to reserve for padding.
|
|
269
|
+
* @default 4
|
|
270
|
+
*/
|
|
228
271
|
rowPadding?: number;
|
|
229
272
|
}
|
|
230
|
-
|
|
273
|
+
/**
|
|
274
|
+
* Trims an option list to what fits the terminal, while keeping the active
|
|
275
|
+
* option (cursor) visible using a Clack style sliding window.
|
|
276
|
+
*
|
|
277
|
+
* @returns The lines to render.
|
|
278
|
+
*
|
|
279
|
+
* @see https://bomb.sh/docs/clack/packages/prompts/#limitoptions
|
|
280
|
+
*
|
|
281
|
+
* @example
|
|
282
|
+
* ```ts
|
|
283
|
+
* import { limitOptions } from '@voidzero-dev/vite-plus-prompts';
|
|
284
|
+
* import color from 'picocolors';
|
|
285
|
+
*
|
|
286
|
+
* const options = ['apple', 'banana', 'cherry', 'date'];
|
|
287
|
+
* const lines = limitOptions({
|
|
288
|
+
* options,
|
|
289
|
+
* cursor: 2,
|
|
290
|
+
* maxItems: 8,
|
|
291
|
+
* style: (opt, active) =>
|
|
292
|
+
* active ? color.blue(opt) : color.dim(opt),
|
|
293
|
+
* });
|
|
294
|
+
* ```
|
|
295
|
+
*/
|
|
296
|
+
export declare const limitOptions: <TOption>({ cursor, options, style, output, maxItems, columnPadding, rowPadding }: LimitOptionsParams<TOption>) => string[];
|
|
231
297
|
//#endregion
|
|
232
298
|
//#region src/log.d.ts
|
|
233
299
|
export interface LogMessageOptions extends CommonOptions {
|
|
@@ -260,8 +326,8 @@ export declare const outro: (message?: string, opts?: CommonOptions) => void;
|
|
|
260
326
|
* piped output never see these markers as content (they only update the
|
|
261
327
|
* window title, which the runner's PTY captures).
|
|
262
328
|
*
|
|
263
|
-
* Protocol (shared with vite-task's `
|
|
264
|
-
* `OSC 2 ; pty-terminal-test:<32-hex-id>:<base64url(name)> ST`. The runner
|
|
329
|
+
* Protocol (shared with vite-task's `vt_pty_terminal_test_client` crate):
|
|
330
|
+
* `OSC 2 ; vt-pty-terminal-test:<32-hex-id>:<base64url(name)> ST`. The runner
|
|
265
331
|
* decodes the title with `decode_milestone_title`, ignoring ordinary title
|
|
266
332
|
* updates. A fresh random id per emission keeps repeated milestones with the
|
|
267
333
|
* same name observable as distinct title changes through Windows ConPTY.
|
|
@@ -288,34 +354,79 @@ export interface MultiSelectOptions<Value> extends CommonOptions {
|
|
|
288
354
|
maxItems?: number;
|
|
289
355
|
required?: boolean;
|
|
290
356
|
cursorAt?: Value;
|
|
357
|
+
showInstructions?: boolean;
|
|
291
358
|
}
|
|
292
|
-
export declare const multiselect: <Value>(opts: MultiSelectOptions<Value>) => Promise<Value[] |
|
|
359
|
+
export declare const multiselect: <Value>(opts: MultiSelectOptions<Value>) => Promise<Value[] | typeof CANCEL_SYMBOL$1>;
|
|
293
360
|
//#endregion
|
|
294
361
|
//#region src/note.d.ts
|
|
295
|
-
type FormatFn = (line: string) => string;
|
|
296
362
|
export interface NoteOptions extends CommonOptions {
|
|
297
|
-
|
|
363
|
+
/** Format note content; readable, un-dimmed text by default. */
|
|
364
|
+
format?: (line: string) => string;
|
|
298
365
|
}
|
|
366
|
+
/** A compact, enclosed note. Guide bars never replace its side borders. */
|
|
299
367
|
export declare const note: (message?: string, title?: string, opts?: NoteOptions) => void;
|
|
300
368
|
//#endregion
|
|
301
369
|
//#region src/password.d.ts
|
|
302
370
|
export interface PasswordOptions extends CommonOptions {
|
|
303
371
|
message: string;
|
|
304
372
|
mask?: string;
|
|
305
|
-
|
|
373
|
+
/** Hint displayed only while the password is empty. */
|
|
374
|
+
placeholder?: string;
|
|
375
|
+
validate?: Validate<string>;
|
|
306
376
|
clearOnError?: boolean;
|
|
307
377
|
}
|
|
308
|
-
export declare const password: (opts: PasswordOptions) => Promise<string |
|
|
378
|
+
export declare const password: (opts: PasswordOptions) => Promise<string | typeof CANCEL_SYMBOL$1>;
|
|
309
379
|
//#endregion
|
|
310
380
|
//#region src/path.d.ts
|
|
381
|
+
/**
|
|
382
|
+
* Options for the {@link path} prompt.
|
|
383
|
+
*/
|
|
311
384
|
export interface PathOptions extends CommonOptions {
|
|
385
|
+
/**
|
|
386
|
+
* The message or question shown to the user above the input.
|
|
387
|
+
*/
|
|
388
|
+
message: string;
|
|
389
|
+
/**
|
|
390
|
+
* The starting directory for path suggestions (defaults to current working directory).
|
|
391
|
+
*/
|
|
312
392
|
root?: string;
|
|
393
|
+
/**
|
|
394
|
+
* When `true` only **directories** appear in suggestions while you navigate.
|
|
395
|
+
*/
|
|
313
396
|
directory?: boolean;
|
|
397
|
+
/**
|
|
398
|
+
* The starting path shown when the prompt first renders, which users can edit
|
|
399
|
+
* before submitting. If not provided it will fall back to the given `root`,
|
|
400
|
+
* or the current working directory.
|
|
401
|
+
*
|
|
402
|
+
* In `directory` mode, if the initial value points to a directory that exists,
|
|
403
|
+
* pressing enter will submit the input instead of jumping to the first child.
|
|
404
|
+
*/
|
|
314
405
|
initialValue?: string;
|
|
315
|
-
|
|
316
|
-
|
|
406
|
+
/**
|
|
407
|
+
* A function or a [Standard Schema](https://github.com/standard-schema/standard-schema)
|
|
408
|
+
* that validates user input. If a custom function is given, you should return a `string` or `Error`
|
|
409
|
+
* to show as a validation error, or `undefined` to accept the result.
|
|
410
|
+
*/
|
|
411
|
+
validate?: Validate<string>;
|
|
317
412
|
}
|
|
318
|
-
|
|
413
|
+
/**
|
|
414
|
+
* The `path` prompt extends `autocomplete` to provide file and directory suggestions.
|
|
415
|
+
*
|
|
416
|
+
* @see https://bomb.sh/docs/clack/packages/prompts/#path-selection
|
|
417
|
+
*
|
|
418
|
+
* @example
|
|
419
|
+
* ```ts
|
|
420
|
+
* import { path } from '@voidzero-dev/vite-plus-prompts';
|
|
421
|
+
*
|
|
422
|
+
* const result = await path({
|
|
423
|
+
* message: 'Select a file:',
|
|
424
|
+
* root: process.cwd(),
|
|
425
|
+
* directory: false,
|
|
426
|
+
* });
|
|
427
|
+
* ```
|
|
428
|
+
*/
|
|
429
|
+
export declare const path: (opts: PathOptions) => Promise<string | typeof CANCEL_SYMBOL$1>;
|
|
319
430
|
//#endregion
|
|
320
431
|
//#region src/spinner.d.ts
|
|
321
432
|
export interface SpinnerOptions extends CommonOptions {
|
|
@@ -358,7 +469,7 @@ export interface SelectKeyOptions<Value extends string> extends CommonOptions {
|
|
|
358
469
|
initialValue?: Value;
|
|
359
470
|
caseSensitive?: boolean;
|
|
360
471
|
}
|
|
361
|
-
export declare const selectKey: <Value extends string>(opts: SelectKeyOptions<Value>) => Promise<Value |
|
|
472
|
+
export declare const selectKey: <Value extends string>(opts: SelectKeyOptions<Value>) => Promise<Value | typeof CANCEL_SYMBOL$1>;
|
|
362
473
|
//#endregion
|
|
363
474
|
//#region src/stream.d.ts
|
|
364
475
|
export declare const stream: {
|
|
@@ -425,8 +536,8 @@ export interface TextOptions extends CommonOptions {
|
|
|
425
536
|
placeholder?: string;
|
|
426
537
|
defaultValue?: string;
|
|
427
538
|
initialValue?: string;
|
|
428
|
-
validate?:
|
|
539
|
+
validate?: Validate<string>;
|
|
429
540
|
}
|
|
430
|
-
export declare const text: (opts: TextOptions) => Promise<string |
|
|
541
|
+
export declare const text: (opts: TextOptions) => Promise<string | typeof CANCEL_SYMBOL$1>;
|
|
431
542
|
//#endregion
|
|
432
|
-
export { type ClackSettings, isCancel, settings, symbol$1 as symbol, updateSettings };
|
|
543
|
+
export { CANCEL_SYMBOL, type ClackSettings, isCancel, settings, symbol$1 as symbol, updateSettings };
|