@inquirer/select 4.3.4 → 4.4.0

package/README.md

@@ -95,15 +95,14 @@ const answer = await select({
 
 ## Options
 
-| Property     | Type                                     | Required | Description                                                                                                                                 |
-| ------------ | ---------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| message      | `string`                                 | yes      | The question to ask                                                                                                                         |
-| choices      | `Choice[]`                               | yes      | List of the available choices.                                                                                                              |
-| default      | `string`                                 | no       | Defines in front of which item the cursor will initially appear. When omitted, the cursor will appear on the first selectable item.         |
-| pageSize     | `number`                                 | no       | By default, lists of choice longer than 7 will be paginated. Use this option to control how many choices will appear on the screen at once. |
-| loop         | `boolean`                                | no       | Defaults to `true`. When set to `false`, the cursor will be constrained to the top and bottom of the choice list without looping.           |
-| instructions | `{ navigation: string; pager: string; }` | no       | Defines the help tip content.                                                                                                               |
-| theme        | [See Theming](#Theming)                  | no       | Customize look of the prompt.                                                                                                               |
+| Property | Type                    | Required | Description                                                                                                                                 |
+| -------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| message  | `string`                | yes      | The question to ask                                                                                                                         |
+| choices  | `Choice[]`              | yes      | List of the available choices.                                                                                                              |
+| default  | `string`                | no       | Defines in front of which item the cursor will initially appear. When omitted, the cursor will appear on the first selectable item.         |
+| pageSize | `number`                | no       | By default, lists of choice longer than 7 will be paginated. Use this option to control how many choices will appear on the screen at once. |
+| loop     | `boolean`               | no       | Defaults to `true`. When set to `false`, the cursor will be constrained to the top and bottom of the choice list without looping.           |
+| theme    | [See Theming](#Theming) | no       | Customize look of the prompt.                                                                                                               |
 
 `Separator` objects can be used in the `choices` array to render non-selectable lines in the choice list. By default it'll render a line, but you can provide the text as argument (`new Separator('-- Dependencies --')`). This option is often used to add labels to groups within long list of options.
 
@@ -150,20 +149,34 @@ type Theme = {
     highlight: (text: string) => string;
     description: (text: string) => string;
     disabled: (text: string) => string;
+    keysHelpTip: (keys: [key: string, action: string][]) => string | undefined;
   };
   icon: {
     cursor: string;
   };
-  helpMode: 'always' | 'never' | 'auto';
   indexMode: 'hidden' | 'number';
 };
 ```
 
-### `theme.helpMode`
+### `theme.style.keysHelpTip`
 
-- `auto` (default): Hide the help tips after an interaction occurs.
-- `always`: The help tips will always show and never hide.
-- `never`: The help tips will never show.
+This function allows you to customize the keyboard shortcuts help tip displayed below the prompt. It receives an array of key-action pairs and should return a formatted string. You can also hook here to localize the labels to different languages.
+
+It can also returns `undefined` to hide the help tip entirely. This is the replacement for the deprecated theme option `helpMode: 'never'`.
+
+```js
+theme: {
+  style: {
+    keysHelpTip: (keys) => {
+      // Return undefined to hide the help tip completely.
+      return undefined;
+
+      // Or customize the formatting. Or localize the labels.
+      return keys.map(([key, action]) => `${key}: ${action}`).join(' | ');
+    };
+  }
+}
+```
 
 ### `theme.indexMode`
 

package/dist/commonjs/index.d.ts

@@ -1,4 +1,4 @@
-import { Separator, type Theme } from '@inquirer/core';
+import { Separator, type Theme, type Keybinding } from '@inquirer/core';
 import type { PartialDeep } from '@inquirer/type';
 type SelectTheme = {
     icon: {
@@ -7,9 +7,12 @@ type SelectTheme = {
     style: {
         disabled: (text: string) => string;
         description: (text: string) => string;
+        keysHelpTip: (keys: [key: string, action: string][]) => string | undefined;
     };
+    /** @deprecated Use theme.style.keysHelpTip instead */
     helpMode: 'always' | 'never' | 'auto';
     indexMode: 'hidden' | 'number';
+    keybindings: ReadonlyArray<Keybinding>;
 };
 type Choice<Value> = {
     value: Value;

package/dist/commonjs/index.js

@@ -13,9 +13,13 @@ const selectTheme = {
     style: {
         disabled: (text) => yoctocolors_cjs_1.default.dim(`- ${text}`),
         description: (text) => yoctocolors_cjs_1.default.cyan(text),
+        keysHelpTip: (keys) => keys
+            .map(([key, action]) => `${yoctocolors_cjs_1.default.bold(key)} ${yoctocolors_cjs_1.default.dim(action)}`)
+            .join(yoctocolors_cjs_1.default.dim(' • ')),
     },
-    helpMode: 'auto',
+    helpMode: 'always',
     indexMode: 'hidden',
+    keybindings: [],
 };
 function isSelectable(item) {
     return !core_1.Separator.isSeparator(item) && !item.disabled;
@@ -47,11 +51,14 @@ function normalizeChoices(choices) {
 }
 exports.default = (0, core_1.createPrompt)((config, done) => {
     const { loop = true, pageSize = 7 } = config;
-    const firstRender = (0, core_1.useRef)(true);
     const theme = (0, core_1.makeTheme)(selectTheme, config.theme);
+    const { keybindings } = theme;
     const [status, setStatus] = (0, core_1.useState)('idle');
     const prefix = (0, core_1.usePrefix)({ status, theme });
     const searchTimeoutRef = (0, core_1.useRef)();
+    // Vim keybindings (j/k) conflict with typing those letters in search,
+    // so search must be disabled when vim bindings are enabled
+    const searchEnabled = !keybindings.includes('vim');
     const items = (0, core_1.useMemo)(() => normalizeChoices(config.choices), [config.choices]);
     const bounds = (0, core_1.useMemo)(() => {
         const first = items.findIndex(isSelectable);
@@ -75,12 +82,12 @@ exports.default = (0, core_1.createPrompt)((config, done) => {
             setStatus('done');
             done(selectedChoice.value);
         }
-        else if ((0, core_1.isUpKey)(key) || (0, core_1.isDownKey)(key)) {
+        else if ((0, core_1.isUpKey)(key, keybindings) || (0, core_1.isDownKey)(key, keybindings)) {
             rl.clearLine(0);
             if (loop ||
-                ((0, core_1.isUpKey)(key) && active !== bounds.first) ||
-                ((0, core_1.isDownKey)(key) && active !== bounds.last)) {
-                const offset = (0, core_1.isUpKey)(key) ? -1 : 1;
+                ((0, core_1.isUpKey)(key, keybindings) && active !== bounds.first) ||
+                ((0, core_1.isDownKey)(key, keybindings) && active !== bounds.last)) {
+                const offset = (0, core_1.isUpKey)(key, keybindings) ? -1 : 1;
                 let next = active;
                 do {
                     next = (next + offset + items.length) % items.length;
@@ -109,8 +116,7 @@ exports.default = (0, core_1.createPrompt)((config, done) => {
         else if ((0, core_1.isBackspaceKey)(key)) {
             rl.clearLine(0);
         }
-        else {
-            // Default to search
+        else if (searchEnabled) {
             const searchTerm = rl.line.toLowerCase();
             const matchIndex = items.findIndex((item) => {
                 if (core_1.Separator.isSeparator(item) || !isSelectable(item))
@@ -129,16 +135,20 @@ exports.default = (0, core_1.createPrompt)((config, done) => {
         clearTimeout(searchTimeoutRef.current);
     }, []);
     const message = theme.style.message(config.message, status);
-    let helpTipTop = '';
-    let helpTipBottom = '';
-    if (theme.helpMode === 'always' ||
-        (theme.helpMode === 'auto' && firstRender.current)) {
-        firstRender.current = false;
-        if (items.length > pageSize) {
-            helpTipBottom = `\n${theme.style.help(`(${config.instructions?.pager ?? 'Use arrow keys to reveal more choices'})`)}`;
+    let helpLine;
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    if (theme.helpMode !== 'never') {
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
+        if (config.instructions) {
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
+            const { pager, navigation } = config.instructions;
+            helpLine = theme.style.help(items.length > pageSize ? pager : navigation);
         }
         else {
-            helpTipTop = theme.style.help(`(${config.instructions?.navigation ?? 'Use arrow keys'})`);
+            helpLine = theme.style.keysHelpTip([
+                ['↑↓', 'navigate'],
+                ['⏎', 'select'],
+            ]);
         }
     }
     let separatorCount = 0;
@@ -163,12 +173,22 @@ exports.default = (0, core_1.createPrompt)((config, done) => {
         loop,
     });
     if (status === 'done') {
-        return `${prefix} ${message} ${theme.style.answer(selectedChoice.short)}`;
+        return [prefix, message, theme.style.answer(selectedChoice.short)]
+            .filter(Boolean)
+            .join(' ');
     }
-    const choiceDescription = selectedChoice.description
-        ? `\n${theme.style.description(selectedChoice.description)}`
-        : ``;
-    return `${[prefix, message, helpTipTop].filter(Boolean).join(' ')}\n${page}${helpTipBottom}${choiceDescription}${ansi_1.cursorHide}`;
+    const { description } = selectedChoice;
+    const lines = [
+        [prefix, message].filter(Boolean).join(' '),
+        page,
+        ' ',
+        description ? theme.style.description(description) : '',
+        helpLine,
+    ]
+        .filter(Boolean)
+        .join('\n')
+        .trimEnd();
+    return `${lines}${ansi_1.cursorHide}`;
 });
 var core_2 = require("@inquirer/core");
 Object.defineProperty(exports, "Separator", { enumerable: true, get: function () { return core_2.Separator; } });

package/dist/esm/index.d.ts

@@ -1,4 +1,4 @@
-import { Separator, type Theme } from '@inquirer/core';
+import { Separator, type Theme, type Keybinding } from '@inquirer/core';
 import type { PartialDeep } from '@inquirer/type';
 type SelectTheme = {
     icon: {
@@ -7,9 +7,12 @@ type SelectTheme = {
     style: {
         disabled: (text: string) => string;
         description: (text: string) => string;
+        keysHelpTip: (keys: [key: string, action: string][]) => string | undefined;
     };
+    /** @deprecated Use theme.style.keysHelpTip instead */
     helpMode: 'always' | 'never' | 'auto';
     indexMode: 'hidden' | 'number';
+    keybindings: ReadonlyArray<Keybinding>;
 };
 type Choice<Value> = {
     value: Value;

package/dist/esm/index.js

@@ -7,9 +7,13 @@ const selectTheme = {
     style: {
         disabled: (text) => colors.dim(`- ${text}`),
         description: (text) => colors.cyan(text),
+        keysHelpTip: (keys) => keys
+            .map(([key, action]) => `${colors.bold(key)} ${colors.dim(action)}`)
+            .join(colors.dim(' • ')),
     },
-    helpMode: 'auto',
+    helpMode: 'always',
     indexMode: 'hidden',
+    keybindings: [],
 };
 function isSelectable(item) {
     return !Separator.isSeparator(item) && !item.disabled;
@@ -41,11 +45,14 @@ function normalizeChoices(choices) {
 }
 export default createPrompt((config, done) => {
     const { loop = true, pageSize = 7 } = config;
-    const firstRender = useRef(true);
     const theme = makeTheme(selectTheme, config.theme);
+    const { keybindings } = theme;
     const [status, setStatus] = useState('idle');
     const prefix = usePrefix({ status, theme });
     const searchTimeoutRef = useRef();
+    // Vim keybindings (j/k) conflict with typing those letters in search,
+    // so search must be disabled when vim bindings are enabled
+    const searchEnabled = !keybindings.includes('vim');
     const items = useMemo(() => normalizeChoices(config.choices), [config.choices]);
     const bounds = useMemo(() => {
         const first = items.findIndex(isSelectable);
@@ -69,12 +76,12 @@ export default createPrompt((config, done) => {
             setStatus('done');
             done(selectedChoice.value);
         }
-        else if (isUpKey(key) || isDownKey(key)) {
+        else if (isUpKey(key, keybindings) || isDownKey(key, keybindings)) {
             rl.clearLine(0);
             if (loop ||
-                (isUpKey(key) && active !== bounds.first) ||
-                (isDownKey(key) && active !== bounds.last)) {
-                const offset = isUpKey(key) ? -1 : 1;
+                (isUpKey(key, keybindings) && active !== bounds.first) ||
+                (isDownKey(key, keybindings) && active !== bounds.last)) {
+                const offset = isUpKey(key, keybindings) ? -1 : 1;
                 let next = active;
                 do {
                     next = (next + offset + items.length) % items.length;
@@ -103,8 +110,7 @@ export default createPrompt((config, done) => {
         else if (isBackspaceKey(key)) {
             rl.clearLine(0);
         }
-        else {
-            // Default to search
+        else if (searchEnabled) {
             const searchTerm = rl.line.toLowerCase();
             const matchIndex = items.findIndex((item) => {
                 if (Separator.isSeparator(item) || !isSelectable(item))
@@ -123,16 +129,20 @@ export default createPrompt((config, done) => {
         clearTimeout(searchTimeoutRef.current);
     }, []);
     const message = theme.style.message(config.message, status);
-    let helpTipTop = '';
-    let helpTipBottom = '';
-    if (theme.helpMode === 'always' ||
-        (theme.helpMode === 'auto' && firstRender.current)) {
-        firstRender.current = false;
-        if (items.length > pageSize) {
-            helpTipBottom = `\n${theme.style.help(`(${config.instructions?.pager ?? 'Use arrow keys to reveal more choices'})`)}`;
+    let helpLine;
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    if (theme.helpMode !== 'never') {
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
+        if (config.instructions) {
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
+            const { pager, navigation } = config.instructions;
+            helpLine = theme.style.help(items.length > pageSize ? pager : navigation);
         }
         else {
-            helpTipTop = theme.style.help(`(${config.instructions?.navigation ?? 'Use arrow keys'})`);
+            helpLine = theme.style.keysHelpTip([
+                ['↑↓', 'navigate'],
+                ['⏎', 'select'],
+            ]);
         }
     }
     let separatorCount = 0;
@@ -157,11 +167,21 @@ export default createPrompt((config, done) => {
         loop,
     });
     if (status === 'done') {
-        return `${prefix} ${message} ${theme.style.answer(selectedChoice.short)}`;
+        return [prefix, message, theme.style.answer(selectedChoice.short)]
+            .filter(Boolean)
+            .join(' ');
     }
-    const choiceDescription = selectedChoice.description
-        ? `\n${theme.style.description(selectedChoice.description)}`
-        : ``;
-    return `${[prefix, message, helpTipTop].filter(Boolean).join(' ')}\n${page}${helpTipBottom}${choiceDescription}${cursorHide}`;
+    const { description } = selectedChoice;
+    const lines = [
+        [prefix, message].filter(Boolean).join(' '),
+        page,
+        ' ',
+        description ? theme.style.description(description) : '',
+        helpLine,
+    ]
+        .filter(Boolean)
+        .join('\n')
+        .trimEnd();
+    return `${lines}${cursorHide}`;
 });
 export { Separator } from '@inquirer/core';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inquirer/select",
-  "version": "4.3.4",
+  "version": "4.4.0",
   "description": "Inquirer select/list prompt",
   "keywords": [
     "answer",
@@ -74,15 +74,15 @@
     "tsc": "tshy"
   },
   "dependencies": {
-    "@inquirer/ansi": "^1.0.0",
-    "@inquirer/core": "^10.2.2",
-    "@inquirer/figures": "^1.0.13",
-    "@inquirer/type": "^3.0.8",
+    "@inquirer/ansi": "^1.0.1",
+    "@inquirer/core": "^10.3.0",
+    "@inquirer/figures": "^1.0.14",
+    "@inquirer/type": "^3.0.9",
     "yoctocolors-cjs": "^2.1.2"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
-    "@inquirer/testing": "^2.1.50",
+    "@inquirer/testing": "^2.1.51",
     "tshy": "^3.0.2"
   },
   "engines": {
@@ -108,5 +108,5 @@
       "optional": true
     }
   },
-  "gitHead": "3fdf43342deb468ee41d698e407d8800700e08dc"
+  "gitHead": "87cb01e67a25983bdaf0d74a7685915c0afb5f23"
 }