@topcli/prompts 3.0.0 → 4.0.0

package/README.md

@@ -55,6 +55,8 @@ Simple prompt, similar to `rl.question()` with an improved UI.
 
 Use `options.defaultValue` to set a default value.
 
+Use `options.hint` to display a hint alongside the question.
+
 Use `options.secure` if you need to hide both input and answer. You can provide either a **boolean** or an **object** which allows to configure a `placeholder` such as `*`.
 
 Use `options.signal` to set an `AbortSignal` (throws a [AbortError](#aborterror)).
@@ -170,7 +172,36 @@ Use `options.caseSensitive` to make autocomplete filters case sensitive. Default
 
 Use `options.signal` to set an `AbortSignal` (throws a [AbortError](#aborterror)).
 
-Use `options.skip` to skip prompt. It will return the first choice.
+Use `options.skip` to skip prompt. It will return the first non-separator choice.
+
+Use `Separator` items in `choices` to visually group options. Separators are not selectable and are skipped during keyboard navigation. When `autocomplete` is active and the user has typed a filter, separators are hidden.
+
+```js
+import { select } from "@topcli/prompts";
+
+const framework = await select("Choose a framework", {
+  choices: [
+    { type: "separator", label: "Frontend" },
+    { value: "react", label: "React" },
+    { value: "vue", label: "Vue" },
+    { type: "separator", label: "Backend" },
+    { value: "express", label: "Express" },
+    { value: "fastify", label: "Fastify" },
+  ]
+});
+```
+
+Use `choice.disabled` to mark a choice as non-selectable.
+
+```js
+const runner = await select("Choose a runner", {
+  choices: [
+    { value: "node", label: "Node.js" },
+    { value: "bun", label: "Bun", disabled: "not available" },
+    { value: "deno", label: "Deno", disabled: true }
+  ]
+});
+```
 
 ### `multiselect()`
 
@@ -193,6 +224,10 @@ Use `options.signal` to set an `AbortSignal` (throws a [AbortError](#aborterror)
 
 Use `options.skip` to skip prompt. It will return `options.preSelectedChoices` if given, `[]` otherwise.
 
+Use `Separator` items in `choices` to visually group options. Separators are not selectable and are skipped during keyboard navigation. When `autocomplete` is active and the user has typed a filter, separators are hidden.
+
+Use `choice.disabled` to mark a choice as non-selectable.
+
 ### `confirm()`
 
 ```ts
@@ -212,14 +247,30 @@ Use `options.skip` to skip prompt. It will return `options.initial` (`false` by
 
 The `PromptAgent` class allows to programmatically set the next answers for any prompt function, this can be useful for testing.
 
+#### Shared instance
+
+`PromptAgent.shared()` returns a singleton shared across all prompt calls that do not receive an explicit `agent` option. Suitable for simple test setups, but beware of state leaking between tests.
+
 ```ts
-const agent = PromptAgent.agent();
+const agent = PromptAgent.shared();
 agent.nextAnswer("John");
 
 const input = await question("What's your name?");
 assert.equal(input, "John");
 ```
 
+#### Individual instance
+
+For better isolation (e.g. in unit tests), create a dedicated `PromptAgent` and pass it via the `agent` option. This avoids any state leaking from the shared instance.
+
+```ts
+const agent = new PromptAgent();
+agent.nextAnswer("John");
+
+const input = await question("What's your name?", { agent });
+assert.equal(input, "John");
+```
+
 > [!WARNING]
 > Answers set with `PromptAgent` will **bypass** any logical & validation rules.
 > Examples:
@@ -278,6 +329,7 @@ export type TransformationResponse<T> = InvalidResponse | ValidTransformationRes
 
 export interface QuestionOptions<T = string> extends AbstractPromptOptions {
   defaultValue?: string;
+  hint?: string;
   validators?: PromptValidator<string>[];
   transformer?: PromptTransformer<T>;
   secure?: boolean | { placeholder: string };
@@ -287,10 +339,16 @@ export interface Choice<T = any> {
   value: T;
   label: string;
   description?: string;
+  disabled?: boolean | string;
+}
+
+export interface Separator {
+  type: "separator";
+  label?: string;
 }
 
 export interface SelectOptions<T extends string> extends AbstractPromptOptions {
-  choices: (Choice<T> | T)[];
+  choices: (Choice<T> | T | Separator)[];
   maxVisible?: number;
   ignoreValues?: (T | number | boolean)[];
   validators?: PromptValidator<string>[];
@@ -299,7 +357,7 @@ export interface SelectOptions<T extends string> extends AbstractPromptOptions {
 }
 
 export interface MultiselectOptions<T extends string> extends AbstractPromptOptions {
-  choices: (Choice<T> | T)[];
+  choices: (Choice<T> | T | Separator)[];
   maxVisible?: number;
   preSelectedChoices?: (Choice<T> | T)[];
   validators?: PromptValidator<string[]>[];

package/dist/index.d.mts

@@ -0,0 +1,140 @@
+import EventEmitter from "node:events";
+import readline from "node:readline";
+
+//#region src/validators.d.ts
+type ValidResponseObject = {
+  isValid?: true;
+};
+type InvalidResponseObject = {
+  isValid: false;
+  error: string;
+};
+type ValidationResponseObject = ValidResponseObject | InvalidResponseObject;
+type ValidationResponse = InvalidResponse | ValidResponse;
+type InvalidResponse = string | InvalidResponseObject;
+type ValidResponse = null | undefined | true | ValidResponseObject;
+type ValidTransformationResponse<T> = {
+  isValid: true;
+  transformed: T;
+};
+type TransformationResponse<T> = InvalidResponse | ValidTransformationResponse<T>;
+interface PromptValidator<T extends string | string[]> {
+  validate: (input: T) => ValidationResponse | Promise<ValidationResponse>;
+}
+interface PromptTransformer<T> {
+  transform: (input: string) => TransformationResponse<T> | Promise<TransformationResponse<T>>;
+}
+declare function required(): PromptValidator<any>;
+//#endregion
+//#region src/prompt-agent.d.ts
+declare class PromptAgent<T = string> {
+  #private;
+  /**
+   * The prompts answers queue.
+   * When not empty, any prompt will be answered by the first answer in this list.
+   */
+  nextAnswers: T[];
+  static shared<T>(): PromptAgent<any>;
+  /**
+   * Programmatically set the next answer for any prompt (`question()`, `confirm()`, `select()`)
+   *
+   * This is useful for testing.
+   *
+   * @example
+   * ```js
+   * const promptAgent = PromptAgent.shared();
+   * promptAgent.nextAnswer("toto");
+   *
+   * const input = await question("what is your name?");
+   * assert.equal(input, "toto");
+   * ```
+   */
+  nextAnswer(value: T | T[]): void;
+  clear(): void;
+}
+//#endregion
+//#region src/transformers.d.ts
+declare function number(): PromptTransformer<number>;
+declare function integer(): PromptTransformer<number>;
+declare function url(): PromptTransformer<URL>;
+//#endregion
+//#region src/types.d.ts
+interface Choice<T extends string> {
+  value: T;
+  label: string;
+  description?: string;
+  disabled?: boolean | string;
+}
+interface Separator {
+  type: "separator";
+  label?: string;
+}
+//#endregion
+//#region src/prompts/abstract.d.ts
+type Stdin = NodeJS.ReadStream & {
+  fd: 0;
+};
+type Stdout = NodeJS.WriteStream & {
+  fd: 1;
+};
+interface AbstractPromptOptions {
+  stdin?: Stdin;
+  stdout?: Stdout;
+  message: string;
+  skip?: boolean;
+  signal?: AbortSignal;
+  agent?: PromptAgent<string | boolean>;
+}
+//#endregion
+//#region src/prompts/question.d.ts
+interface QuestionOptions<T = string> extends AbstractPromptOptions {
+  defaultValue?: string;
+  hint?: string;
+  validators?: PromptValidator<string>[];
+  transformer?: PromptTransformer<T>;
+  secure?: boolean | {
+    placeholder: string;
+  };
+}
+//#endregion
+//#region src/prompts/confirm.d.ts
+interface ConfirmOptions extends AbstractPromptOptions {
+  initial?: boolean;
+}
+//#endregion
+//#region src/prompts/select.d.ts
+interface SelectOptions<T extends string> extends AbstractPromptOptions {
+  choices: (Choice<T> | T | Separator)[];
+  maxVisible?: number;
+  ignoreValues?: (T | number | boolean)[];
+  validators?: PromptValidator<string>[];
+  autocomplete?: boolean;
+  caseSensitive?: boolean;
+}
+//#endregion
+//#region src/prompts/multiselect.d.ts
+interface MultiselectOptions<T extends string> extends AbstractPromptOptions {
+  choices: (Choice<T> | T | Separator)[];
+  maxVisible?: number;
+  preSelectedChoices?: (Choice<T> | T)[];
+  validators?: PromptValidator<string[]>[];
+  autocomplete?: boolean;
+  caseSensitive?: boolean;
+  showHint?: boolean;
+}
+//#endregion
+//#region src/index.d.ts
+declare function question<T = string>(message: string, options?: Omit<QuestionOptions<T>, "message">): Promise<T>;
+declare function select<T extends string>(message: string, options: Omit<SelectOptions<T>, "message">): Promise<T>;
+declare function confirm(message: string, options?: Omit<ConfirmOptions, "message">): Promise<boolean>;
+declare function multiselect<T extends string>(message: string, options: Omit<MultiselectOptions<T>, "message">): Promise<T[]>;
+declare const validators: {
+  required: typeof required;
+};
+declare const transformers: {
+  number: typeof number;
+  integer: typeof integer;
+  url: typeof url;
+};
+//#endregion
+export { type AbstractPromptOptions, type Choice, type ConfirmOptions, type InvalidResponse, type InvalidResponseObject, type MultiselectOptions, PromptAgent, type PromptTransformer, type PromptValidator, type QuestionOptions, type SelectOptions, type Separator, type TransformationResponse, type ValidResponse, type ValidResponseObject, type ValidTransformationResponse, type ValidationResponse, type ValidationResponseObject, confirm, multiselect, question, select, transformers, validators };