@voidzero-dev/vite-plus-prompts 1.0.0-rc.1 → 1.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/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 | symbol>;
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?: (value: Value | Value[] | undefined) => string | Error | undefined;
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 | symbol>;
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[] | symbol>;
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 | symbol>;
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[] | symbol>;
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
- maxItems: number | undefined;
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
- export declare const limitOptions: <TOption>(params: LimitOptionsParams<TOption>) => string[];
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 {
@@ -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[] | symbol>;
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
- format?: FormatFn;
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
- validate?: (value: string | undefined) => string | Error | undefined;
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 | symbol>;
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
- message: string;
316
- validate?: (value: string | undefined) => string | Error | undefined;
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
- export declare const path: (opts: PathOptions) => Promise<string | symbol>;
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 | symbol>;
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?: (value: string | undefined) => string | Error | undefined;
539
+ validate?: Validate<string>;
429
540
  }
430
- export declare const text: (opts: TextOptions) => Promise<string | symbol>;
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 };