@topcli/prompts 1.3.1 → 1.4.0

package/README.md

@@ -27,15 +27,19 @@ $ yarn add @topcli/prompts
 You can locally run `node ./demo.js`
 
 ```js
-import { question, confirm, select } from "@topcli/prompts";
+import { question, confirm, select, multiselect } from "@topcli/prompts";
 
 const kTestRunner = ["node", "tap", "tape", "vitest", "mocha", "ava"];
 
 const name = await question("Project name ?", { defaultValue: "foo" });
 const runner = await select("Choose a test runner", { choices: kTestRunner, maxVisible: 5 });
 const isCLI = await confirm("Your project is a CLI ?", { initial: true });
+const os = await multiselect("Choose OS", {
+  choices: ["linux", "mac", "windows"],
+  preSelectedChoices: ["linux"]
+});
 
-console.log(name, runner, isCLI);
+console.log(name, runner, isCLI, os);
 ```
 
 ## API
@@ -83,6 +87,26 @@ select(message: string, options: SelectOptions): Promise<string>
 Scrollable select depending `maxVisible` (default `8`).
 Use `ignoreValues` to skip result render & clear lines after a selected one.
 
+### `multiselect()`
+
+```ts
+multiselect(message: string, options: MultiselectOptions): Promise<[string]>
+```
+
+Scrollable multiselect depending `maxVisible` (default `8`).  
+Use `preSelectedChoices` to pre-select choices.
+
+Use `validators` to handle user input.
+
+**Example**
+
+```js
+const os = await multiselect('Choose OS', {
+  choices: ["linux", "mac", "windows"]
+  validators: [required()]
+});
+```
+
 ### `confirm()`
 
 ```ts
@@ -109,6 +133,7 @@ assert.equal(input, "John");
 > - When using `question()`, `validators` functions will not be executed.
 > - When using `select()`, the answer can be different from the available choices.
 > - When using `confirm()`, the answer can be any type other than boolean.
+> - etc  
 > **Use with caution**
 
 ## Interfaces
@@ -145,6 +170,13 @@ export interface SelectOptions extends SharedOptions  {
   ignoreValues?: (string | number | boolean)[];
 }
 
+export interface MultiselectOptions extends SharedOptions  {
+  choices: (Choice | string)[];
+  maxVisible?: number;
+  preSelectedChoices?: (Choice | string)[];
+  validators?: Validator[];
+}
+
 export interface ConfirmOptions extends SharedOptions  {
   initial?: boolean;
 }

package/index.d.ts

@@ -17,7 +17,6 @@ export interface QuestionOptions extends SharedOptions {
   validators?: Validator[];
 }
 
-
 export interface Choice {
   value: any;
   label: string;
@@ -30,12 +29,20 @@ export interface SelectOptions extends SharedOptions  {
   ignoreValues?: (string | number | boolean)[];
 }
 
+export interface MultiselectOptions extends SharedOptions  {
+  choices: (Choice | string)[];
+  maxVisible?: number;
+  preSelectedChoices?: (Choice | string)[];
+  validators?: Validator[];
+}
+
 export interface ConfirmOptions extends SharedOptions  {
   initial?: boolean;
 }
 
 export function question(message: string, options?: QuestionOptions): Promise<string>;
 export function select(message: string, options: SelectOptions): Promise<string>;
+export function multiselect(message: string, options: MultiselectOptions): Promise<string[]>;
 export function confirm(message: string, options?: ConfirmOptions): Promise<boolean>;
 
 export function required(): Validator;

package/index.js

@@ -4,6 +4,7 @@ import { SelectPrompt } from "./src/select-prompt.js";
 import { QuestionPrompt } from "./src/question-prompt.js";
 import { required } from "./src/validators.js";
 import { PromptAgent } from "./src/prompt-agent.js";
+import { MultiselectPrompt } from "./src/multiselect-prompt.js";
 
 export async function question(message, options = {}) {
   const questionPrompt = new QuestionPrompt(message, options);
@@ -23,4 +24,10 @@ export async function confirm(message, options) {
   return confirmPrompt.confirm();
 }
 
+export async function multiselect(message, options) {
+  const multiselectPrompt = new MultiselectPrompt(message, options);
+
+  return multiselectPrompt.multiselect();
+}
+
 export { required, PromptAgent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topcli/prompts",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Node.js user input library for command-line interfaces.",
   "scripts": {
     "test": "node --no-warnings=ExperimentalWarning --loader=esmock --test test/",
@@ -23,11 +23,11 @@
   "license": "ISC",
   "type": "module",
   "devDependencies": {
-    "@nodesecure/eslint-config": "^1.7.0",
-    "@types/node": "^20.4.5",
-    "c8": "^8.0.0",
-    "eslint": "^8.44.0",
-    "esmock": "^2.3.1"
+    "@nodesecure/eslint-config": "^1.8.0",
+    "@types/node": "^20.8.2",
+    "c8": "^8.0.1",
+    "eslint": "^8.50.0",
+    "esmock": "^2.5.1"
   },
   "dependencies": {
     "is-unicode-supported": "^1.3.0",

package/src/abstract-prompt.js

@@ -47,7 +47,7 @@ export class AbstractPrompt {
 
     const lastLineRows = Math.ceil(stripAnsi(lastLine).length / this.stdout.columns);
 
-    this.stdout.moveCursor(0, -lastLineRows);
+    this.stdout.moveCursor(-this.stdout.columns, -lastLineRows);
     this.stdout.clearScreenDown();
   }
 

package/src/constants.js

@@ -7,14 +7,18 @@ const kMainSymbols = {
   cross: "✖",
   pointer: "›",
   previous: "⭡",
-  next: "⭣"
+  next: "⭣",
+  active: "●",
+  inactive: "○"
 };
 const kFallbackSymbols = {
   tick: "√",
   cross: "×",
   pointer: ">",
   previous: "↑",
-  next: "↓"
+  next: "↓",
+  active: "(+)",
+  inactive: "(-)"
 };
 const kSymbols = isUnicodeSupported() ? kMainSymbols : kFallbackSymbols;
 const kPointer = kleur.gray(kSymbols.pointer);
@@ -27,5 +31,7 @@ export const SYMBOLS = {
   Previous: kSymbols.previous,
   Next: kSymbols.next,
   ShowCursor: "\x1B[?25h",
-  HideCursor: "\x1B[?25l"
+  HideCursor: "\x1B[?25l",
+  Active: kleur.cyan(kSymbols.active),
+  Inactive: kleur.gray(kSymbols.inactive)
 };

package/src/multiselect-prompt.js

@@ -0,0 +1,257 @@
+// Import Node.js Dependencies
+import { EOL } from "node:os";
+
+// Import Third-party Dependencies
+import kleur from "kleur";
+
+// Import Internal Dependencies
+import { AbstractPrompt } from "./abstract-prompt.js";
+import { SYMBOLS } from "./constants.js";
+
+export class MultiselectPrompt extends AbstractPrompt {
+  #validators;
+
+  activeIndex = 0;
+  selectedIndexes = [];
+
+  get choices() {
+    return this.options.choices;
+  }
+
+  constructor(message, options) {
+    const {
+      stdin = process.stdin,
+      stdout = process.stdout,
+      choices,
+      preSelectedChoices,
+      validators = []
+    } = options ?? {};
+
+    super(message, stdin, stdout);
+
+    if (!options) {
+      this.destroy();
+      throw new TypeError("Missing required options");
+    }
+
+    this.options = options;
+
+    if (!choices?.length) {
+      this.destroy();
+      throw new TypeError("Missing required param: choices");
+    }
+
+    this.longestChoice = Math.max(...choices.map((choice) => {
+      if (typeof choice === "string") {
+        return choice.length;
+      }
+
+      const kRequiredChoiceProperties = ["label", "value"];
+
+      for (const prop of kRequiredChoiceProperties) {
+        if (!choice[prop]) {
+          this.destroy();
+          throw new TypeError(`Missing ${prop} for choice ${JSON.stringify(choice)}`);
+        }
+      }
+
+      return choice.label.length;
+    }));
+
+    this.#validators = validators;
+
+    if (!preSelectedChoices) {
+      return;
+    }
+
+    for (const choice of preSelectedChoices) {
+      const choiceIndex = this.choices.findIndex((item) => {
+        if (typeof item === "string") {
+          return item === choice;
+        }
+
+        return item.value === choice;
+      });
+
+      if (choiceIndex === -1) {
+        throw new Error(`Invalid pre-selected choice: ${choice.value ?? choice}`);
+      }
+
+      this.selectedIndexes.push(choiceIndex);
+    }
+  }
+
+  #getFormattedChoice(choiceIndex) {
+    const choice = this.choices[choiceIndex];
+
+    if (typeof choice === "string") {
+      return { value: choice, label: choice };
+    }
+
+    return choice;
+  }
+
+  #getVisibleChoices() {
+    const maxVisible = this.options.maxVisible || 8;
+    let startIndex = Math.min(this.choices.length - maxVisible, this.activeIndex - Math.floor(maxVisible / 2));
+    if (startIndex < 0) {
+      startIndex = 0;
+    }
+
+    const endIndex = Math.min(startIndex + maxVisible, this.choices.length);
+
+    return { startIndex, endIndex };
+  }
+
+  #showChoices() {
+    const { startIndex, endIndex } = this.#getVisibleChoices();
+    this.lastRender = { startIndex, endIndex };
+
+    for (let choiceIndex = startIndex; choiceIndex < endIndex; choiceIndex++) {
+      const choice = this.#getFormattedChoice(choiceIndex);
+      const isChoiceActive = choiceIndex === this.activeIndex;
+      const isChoiceSelected = this.selectedIndexes.includes(choiceIndex);
+      const showPreviousChoicesArrow = startIndex > 0 && choiceIndex === startIndex;
+      const showNextChoicesArrow = endIndex < this.choices.length && choiceIndex === endIndex - 1;
+
+      let prefixArrow = "  ";
+      if (showPreviousChoicesArrow) {
+        prefixArrow = SYMBOLS.Previous + " ";
+      }
+      else if (showNextChoicesArrow) {
+        prefixArrow = SYMBOLS.Next + " ";
+      }
+
+      const prefix = `${prefixArrow}${isChoiceSelected ? SYMBOLS.Active : SYMBOLS.Inactive}`;
+      const formattedLabel = choice.label.padEnd(
+        this.longestChoice < 10 ? this.longestChoice : 0
+      );
+      const formattedDescription = choice.description ? ` - ${choice.description}` : "";
+      const color = isChoiceActive ? kleur.white().bold : kleur.gray;
+      const str = `${prefix} ${color(`${formattedLabel}${formattedDescription}`)}${EOL}`;
+
+      this.write(str);
+    }
+  }
+
+  #showAnsweredQuestion(choices, isAgentAnswer = false) {
+    const prefixSymbol = this.selectedIndexes.length === 0 && !isAgentAnswer ? SYMBOLS.Cross : SYMBOLS.Tick;
+    const prefix = `${prefixSymbol} ${kleur.bold(this.message)} ${SYMBOLS.Pointer}`;
+    const formattedChoice = kleur.yellow(choices);
+
+    this.write(`${prefix}${choices ? ` ${formattedChoice}` : ""}${EOL}`);
+  }
+
+  async multiselect() {
+    if (this.agent.nextAnswers.length > 0) {
+      const answer = this.agent.nextAnswers.shift();
+      this.#showAnsweredQuestion(answer, true);
+      this.destroy();
+
+      return answer;
+    }
+
+    this.write(SYMBOLS.HideCursor);
+    this.#showQuestion();
+
+    const render = (options = {}) => {
+      const {
+        initialRender = false,
+        clearRender = false,
+        error = null
+      } = options;
+
+      if (!initialRender) {
+        let linesToClear = this.lastRender.endIndex - this.lastRender.startIndex;
+        while (linesToClear > 0) {
+          this.clearLastLine();
+          linesToClear--;
+        }
+      }
+
+      if (clearRender) {
+        this.stdout.moveCursor(0, -2);
+        this.stdout.clearScreenDown();
+
+        return;
+      }
+
+      if (error) {
+        this.stdout.moveCursor(0, -2);
+        this.stdout.clearScreenDown();
+        this.#showQuestion(error);
+      }
+
+      this.#showChoices();
+    };
+
+    render({ initialRender: true });
+
+    return new Promise((resolve) => {
+      const onKeypress = (value, key) => {
+        if (key.name === "up") {
+          this.activeIndex = this.activeIndex === 0 ? this.choices.length - 1 : this.activeIndex - 1;
+          render();
+        }
+        else if (key.name === "down") {
+          this.activeIndex = this.activeIndex === this.choices.length - 1 ? 0 : this.activeIndex + 1;
+          render();
+        }
+        else if (key.name === "a") {
+          this.selectedIndexes = this.selectedIndexes.length === this.choices.length ? [] : this.choices.map((_, index) => index);
+          render();
+        }
+        else if (key.name === "space") {
+          const isChoiceSelected = this.selectedIndexes.includes(this.activeIndex);
+
+          if (isChoiceSelected) {
+            this.selectedIndexes = this.selectedIndexes.filter((index) => index !== this.activeIndex);
+          }
+          else {
+            this.selectedIndexes.push(this.activeIndex);
+          }
+
+          render();
+        }
+        else if (key.name === "return") {
+          const labels = this.selectedIndexes.map((index) => this.choices[index].label ?? this.choices[index]);
+          const values = this.selectedIndexes.map((index) => this.choices[index].value ?? this.choices[index]);
+
+          for (const validator of this.#validators) {
+            if (!validator.validate(values)) {
+              const error = validator.error(values);
+              render({ error });
+
+              return;
+            }
+          }
+
+          this.stdin.off("keypress", onKeypress);
+
+          render({ clearRender: true });
+
+
+          this.#showAnsweredQuestion(labels.join(", "));
+
+          this.write(SYMBOLS.ShowCursor);
+          this.destroy();
+
+          resolve(values);
+        }
+      };
+
+      this.stdin.on("keypress", onKeypress);
+    });
+  }
+
+  #showQuestion(error = null) {
+    let hint = kleur.gray(
+      `(Press ${kleur.bold("<a>")} to toggle all, ${kleur.bold("<space>")} to select, ${kleur.bold("<return>")} to submit)`
+    );
+    if (error) {
+      hint += ` ${kleur.red().bold(`[${error}]`)}`;
+    }
+
+    this.write(`${SYMBOLS.QuestionMark} ${kleur.bold(this.message)} ${hint}${EOL}`);
+  }
+}

package/src/validators.js

@@ -1,6 +1,6 @@
 export function required() {
   return {
-    validate: (input) => input !== "",
+    validate: (input) => (Array.isArray(input) ? input.length > 0 : Boolean(input)),
     error: () => "required"
   };
 }