feat(question): add hint option (#181)

Author: PierreDemailly

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)).
@@ -311,6 +313,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 };

src/prompts/question.ts

@@ -18,6 +18,7 @@ import {
 
 export interface QuestionOptions<T = string> extends AbstractPromptOptions {
   defaultValue?: string;
+  hint?: string;
   validators?: PromptValidator<string>[];
   transformer?: PromptTransformer<T>;
   secure?: boolean | {
@@ -27,6 +28,7 @@ export interface QuestionOptions<T = string> extends AbstractPromptOptions {
 
 export class QuestionPrompt<T = string> extends AbstractPrompt<string> {
   defaultValue?: string;
+  hint?: string;
   tip: string;
   questionSuffixError: string;
   answer?: string;
@@ -40,6 +42,7 @@ export class QuestionPrompt<T = string> extends AbstractPrompt<string> {
   constructor(options: QuestionOptions<T>) {
     const {
       defaultValue,
+      hint,
       validators = [],
       transformer,
       secure = false,
@@ -57,6 +60,7 @@ export class QuestionPrompt<T = string> extends AbstractPrompt<string> {
     }
 
     this.defaultValue = defaultValue;
+    this.hint = hint;
     this.tip = this.defaultValue ? ` (${this.defaultValue})` : "";
     this.#validators = validators;
     this.#transformer = transformer;
@@ -71,6 +75,10 @@ export class QuestionPrompt<T = string> extends AbstractPrompt<string> {
     this.questionSuffixError = "";
   }
 
+  get formattedHint(): string {
+    return this.hint ? styleText("gray", this.hint) : "";
+  }
+
   #question(): Promise<string> {
     const { resolve, promise } = Promise.withResolvers<string>();
 
@@ -92,7 +100,9 @@ export class QuestionPrompt<T = string> extends AbstractPrompt<string> {
   }
 
   #getQuestionQuery() {
-    return `${styleText("bold", `${SYMBOLS.QuestionMark} ${this.message}${this.tip}`)} ${this.questionSuffixError}`;
+    const hintPart = this.formattedHint ? ` ${this.formattedHint}` : "";
+
+    return `${styleText("bold", `${SYMBOLS.QuestionMark} ${this.message}${this.tip}`)}${hintPart} ${this.questionSuffixError}`;
   }
 
   #setQuestionSuffixError(error: string) {
@@ -117,9 +127,10 @@ export class QuestionPrompt<T = string> extends AbstractPrompt<string> {
 
   #getValidatingQuery(dotCount: number) {
     const question = styleText("bold", `${SYMBOLS.QuestionMark} ${this.message}${this.tip}`);
-    const hint = styleText("yellow", `[validating${".".repeat(dotCount)}]`);
+    const hintPart = this.formattedHint ? ` ${this.formattedHint}` : "";
+    const validating = styleText("yellow", `[validating${".".repeat(dotCount)}]`);
 
-    return `${question} ${hint}${EOL}`;
+    return `${question}${hintPart} ${validating}${EOL}`;
   }
 
   async #runTransformer(): Promise<TransformationResponse<T>> {

test/question-prompt.test.ts

@@ -299,4 +299,21 @@ describe("QuestionPrompt", () => {
       "✔ Enter a number › 123"
     ]);
   });
+
+  it("should display hint in the question query", async() => {
+    const logs: string[] = [];
+    const questionPrompt = await TestingPrompt.QuestionPrompt({
+      message: "What port?",
+      hint: "between 8000 and 8099",
+      inputs: ["8080"],
+      onStdoutWrite: (log) => logs.push(log)
+    });
+    const input = await questionPrompt.listen();
+
+    assert.equal(input, "8080");
+    assert.deepStrictEqual(logs, [
+      "? What port? between 8000 and 8099",
+      "✔ What port? › 8080"
+    ]);
+  });
 });