inquirerjs-checkbox-search 0.1.2 → 0.2.1

package/README.md

@@ -10,36 +10,9 @@ This prompt combines the functionality of `@inquirer/checkbox` and `@inquirer/se
 
 ## Installation
 
-<table>
-<tr>
-  <th>npm</th>
-  <th>yarn</th>
-  <th>pnpm</th>
-</tr>
-<tr>
-<td>
-
-```sh
-npm install inquirerjs-checkbox-search
-```
-
-</td>
-<td>
-
-```sh
-yarn add inquirerjs-checkbox-search
-```
-
-</td>
-<td>
-
-```sh
-pnpm add inquirerjs-checkbox-search
-```
-
-</td>
-</tr>
-</table>
+- **npm**: `npm install inquirerjs-checkbox-search`
+- **yarn**: `yarn add inquirerjs-checkbox-search`
+- **pnpm**: `pnpm add inquirerjs-checkbox-search`
 
 ## Usage
 
@@ -65,19 +38,19 @@ console.log('Selected:', selected);
 
 ### Options
 
-| Property       | Type                                                                                | Required | Description                                            |
-| -------------- | ----------------------------------------------------------------------------------- | -------- | ------------------------------------------------------ |
-| `message`      | `string`                                                                            | Yes      | The question to ask                                    |
-| `choices`      | `Array<Choice \| string \| Separator>`                                              | No\*     | Static list of choices                                 |
-| `source`       | `(term?: string, opt: { signal: AbortSignal }) => Promise<Array<Choice \| string>>` | No\*     | Async function for dynamic choices                     |
-| `pageSize`     | `number`                                                                            | No       | Number of choices to display per page (default: 7)     |
-| `loop`         | `boolean`                                                                           | No       | Whether to loop around when navigating (default: true) |
-| `required`     | `boolean`                                                                           | No       | Require at least one selection (default: false)        |
-| `validate`     | `(selection: Array<Choice>) => boolean \| string \| Promise<string \| boolean>`     | No       | Custom validation function                             |
-| `instructions` | `string \| boolean`                                                                 | No       | Custom instructions text or false to hide              |
-| `theme`        | `Theme`                                                                             | No       | Custom theme configuration                             |
-| `default`      | `Array<Value>`                                                                      | No       | Initially selected values                              |
-| `filter`       | `(items: Array<Choice>, term: string) => Array<Choice>`                             | No       | Custom filter function                                 |
+| Property       | Type                                                                                | Required | Description                                                                                             |
+| -------------- | ----------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------- |
+| `message`      | `string`                                                                            | Yes      | The question to ask                                                                                     |
+| `choices`      | `Array<Choice \| string \| Separator>`                                              | No\*     | Static list of choices                                                                                  |
+| `source`       | `(term?: string, opt: { signal: AbortSignal }) => Promise<Array<Choice \| string>>` | No\*     | Async function for dynamic choices                                                                      |
+| `pageSize`     | `number`                                                                            | No       | Fixed number of choices to display. If not specified, auto-sizes based on terminal height (fallback: 7) |
+| `loop`         | `boolean`                                                                           | No       | Whether to loop around when navigating (default: true)                                                  |
+| `required`     | `boolean`                                                                           | No       | Require at least one selection (default: false)                                                         |
+| `validate`     | `(selection: Array<Choice>) => boolean \| string \| Promise<string \| boolean>`     | No       | Custom validation function                                                                              |
+| `instructions` | `string \| boolean`                                                                 | No       | Custom instructions text or false to hide                                                               |
+| `theme`        | `Theme`                                                                             | No       | Custom theme configuration                                                                              |
+| `default`      | `Array<Value>`                                                                      | No       | Initially selected values                                                                               |
+| `filter`       | `(items: Array<Choice>, term: string) => Array<Choice>`                             | No       | Custom filter function                                                                                  |
 
 \*Either `choices` or `source` must be provided.
 

package/dist/commonjs/index.d.ts

@@ -44,6 +44,12 @@ export type NormalizedChoice<Value> = {
     disabled: boolean | string;
     checked: boolean;
 };
+/**
+ * Calculate dynamic page size based on terminal height
+ * @param fallbackPageSize - Default page size to use if terminal height is not available
+ * @returns Calculated page size
+ */
+export declare function calculateDynamicPageSize(fallbackPageSize: number): number;
 /**
  * Main checkbox-search prompt implementation
  *

package/dist/commonjs/index.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Separator = void 0;
+exports.calculateDynamicPageSize = calculateDynamicPageSize;
 const core_1 = require("@inquirer/core");
 const yoctocolors_cjs_1 = __importDefault(require("yoctocolors-cjs"));
 const figures_1 = __importDefault(require("@inquirer/figures"));
@@ -24,7 +25,7 @@ const checkboxSearchTheme = {
         help: yoctocolors_cjs_1.default.dim,
         highlight: yoctocolors_cjs_1.default.cyan,
         searchTerm: yoctocolors_cjs_1.default.cyan,
-        description: yoctocolors_cjs_1.default.dim,
+        description: yoctocolors_cjs_1.default.cyan,
         disabled: yoctocolors_cjs_1.default.dim,
     },
     helpMode: 'always',
@@ -104,6 +105,40 @@ function defaultFilter(items, term) {
             value.includes(searchTerm));
     });
 }
+/**
+ * Calculate dynamic page size based on terminal height
+ * @param fallbackPageSize - Default page size to use if terminal height is not available
+ * @returns Calculated page size
+ */
+function calculateDynamicPageSize(fallbackPageSize) {
+    let rawPageSize;
+    try {
+        // Get terminal height from process.stdout.rows
+        const terminalHeight = process.stdout.rows;
+        if (!terminalHeight || terminalHeight < 1) {
+            // Fallback to static page size if terminal height is not available
+            rawPageSize = fallbackPageSize;
+        }
+        else {
+            // Reserve space for UI elements:
+            // - 1 line for the prompt message
+            // - 1 line for help instructions
+            // - 1 line for search input (if present)
+            // - 1 line for error messages (if present)
+            // - 1 line for description (if present)
+            // - 1 line for buffer/spacing
+            const reservedLines = 6;
+            // Calculate available lines for choices
+            rawPageSize = terminalHeight - reservedLines;
+        }
+    }
+    catch {
+        // If there's any error accessing terminal dimensions, fallback gracefully
+        rawPageSize = fallbackPageSize;
+    }
+    // Ensure minimum page size for usability and cap maximum to prevent overwhelming display
+    return Math.max(2, Math.min(rawPageSize, 50));
+}
 /**
  * Main checkbox-search prompt implementation
  *
@@ -124,7 +159,15 @@ exports.default = (0, core_1.createPrompt)((config, done) => {
     // Stable reference for empty array to prevent unnecessary recalculations
     const emptyArray = (0, core_1.useMemo)(() => [], []);
     // Configuration with defaults
-    const { pageSize = 7, loop = true, required, validate = () => true, default: defaultValues = emptyArray, } = config;
+    const { pageSize: configPageSize, loop = true, required, validate = () => true, default: defaultValues = emptyArray, } = config;
+    // Calculate effective page size (memoized with terminal size tracking)
+    // If pageSize is specified, use it as fixed size
+    // If not specified, use auto-sizing that recalculates when terminal resizes
+    const terminalHeight = process.stdout.rows; // Track terminal size for memoization
+    const pageSize = (0, core_1.useMemo)(() => configPageSize !== undefined
+        ? configPageSize // Fixed page size
+        : calculateDynamicPageSize(7), // Auto page size with fallback 7
+    [configPageSize, terminalHeight]);
     const theme = (0, core_1.makeTheme)(checkboxSearchTheme, config.theme);
     // State management hooks
     const [status, setStatus] = (0, core_1.useState)('idle');
@@ -147,6 +190,8 @@ exports.default = (0, core_1.createPrompt)((config, done) => {
         }
         return [];
     });
+    // Store the active item value instead of active index
+    const [activeItemValue, setActiveItemValue] = (0, core_1.useState)(null);
     // Compute filtered items based on search term and filtering logic
     const filteredItems = (0, core_1.useMemo)(() => {
         // Async source mode - use allItems directly (source handles filtering)
@@ -175,8 +220,48 @@ exports.default = (0, core_1.createPrompt)((config, done) => {
         }
         return result;
     }, [allItems, searchTerm, config.source, config.filter]);
-    const [active, setActive] = (0, core_1.useState)(0);
+    // Compute active index from activeItemValue
+    const active = (0, core_1.useMemo)(() => {
+        if (activeItemValue === null) {
+            // No active item set, default to first selectable
+            const firstSelectableIndex = filteredItems.findIndex((item) => isSelectable(item));
+            return firstSelectableIndex !== -1 ? firstSelectableIndex : 0;
+        }
+        // Find the item with the active value
+        const activeIndex = filteredItems.findIndex((item) => !core_1.Separator.isSeparator(item) &&
+            item.value === activeItemValue);
+        if (activeIndex !== -1) {
+            return activeIndex;
+        }
+        // Active item not found in filtered list, default to first selectable
+        const firstSelectableIndex = filteredItems.findIndex((item) => isSelectable(item));
+        return firstSelectableIndex !== -1 ? firstSelectableIndex : 0;
+    }, [filteredItems, activeItemValue]);
+    // Update activeItemValue when active index changes (e.g., when filtering results in auto-focus)
+    (0, core_1.useEffect)(() => {
+        const activeItem = filteredItems[active];
+        if (activeItem && !core_1.Separator.isSeparator(activeItem)) {
+            const currentActiveValue = activeItem
+                .value;
+            if (activeItemValue !== currentActiveValue) {
+                setActiveItemValue(currentActiveValue);
+            }
+        }
+    }, [active, filteredItems, activeItemValue]);
     const [errorMsg, setError] = (0, core_1.useState)();
+    // Hide cursor on mount, show on unmount (like other inquirer prompts)
+    (0, core_1.useEffect)(() => {
+        // Hide cursor when prompt starts (only in TTY environments)
+        if (process.stdout.isTTY) {
+            process.stdout.write(ansi_escapes_1.default.cursorHide);
+        }
+        // Show cursor when prompt ends (cleanup function)
+        return () => {
+            if (process.stdout.isTTY) {
+                process.stdout.write(ansi_escapes_1.default.cursorShow);
+            }
+        };
+    }, []);
     // Handle async source - load data based on search term
     (0, core_1.useEffect)(() => {
         if (!config.source) {
@@ -213,31 +298,14 @@ exports.default = (0, core_1.createPrompt)((config, done) => {
     (0, core_1.useEffect)(() => {
         allItemsRef.current = allItems;
     }, [allItems]);
-    // Reset active index when filtered items change, but preserve cursor position during selection toggles
-    (0, core_1.useEffect)(() => {
-        // Don't reset cursor position if we're just toggling selection on the same items
-        // Only reset when the actual set of filtered items changes (not their selection state)
-        const currentFilteredValues = filteredItems
-            .filter((item) => !core_1.Separator.isSeparator(item))
-            .map((item) => item.value);
-        const activeItem = filteredItems[active];
-        const activeValue = activeItem && !core_1.Separator.isSeparator(activeItem)
-            ? activeItem.value
-            : null;
-        // If the currently active item is still in the filtered list, preserve its position
-        if (activeValue && currentFilteredValues.includes(activeValue)) {
-            const newActiveIndex = filteredItems.findIndex((item) => !core_1.Separator.isSeparator(item) &&
-                item.value === activeValue);
-            if (newActiveIndex !== -1) {
-                setActive(newActiveIndex);
-                return;
-            }
-        }
-        // Otherwise reset to 0 (when filtering actually changes the set of items)
-        setActive(0);
-    }, [filteredItems, active]);
     // Keyboard event handling
     (0, core_1.useKeypress)((key, rl) => {
+        // Helper function to update search term in both readline and React state
+        const updateSearchTerm = (newTerm) => {
+            rl.clearLine(0);
+            rl.write(newTerm);
+            setSearchTerm(newTerm);
+        };
         // Allow search input even during loading, but block other actions
         const isNavigationOrAction = key.name === 'up' ||
             key.name === 'down' ||
@@ -251,13 +319,14 @@ exports.default = (0, core_1.createPrompt)((config, done) => {
         setError(undefined);
         // Handle Escape key - clear search term quickly
         if (key.name === 'escape') {
-            rl.line = ''; // Clear readline input first (avoid re-render)
-            setSearchTerm(''); // Then update state
+            updateSearchTerm(''); // Clear both readline and React state
             return;
         }
-        // Handle navigation
-        if ((0, core_1.isUpKey)(key) || (0, core_1.isDownKey)(key)) {
-            const direction = (0, core_1.isUpKey)(key) ? -1 : 1;
+        // Handle navigation - ONLY actual arrow keys (not vim j/k keys)
+        // This follows the official inquirer.js search approach
+        if (key.name === 'up' || key.name === 'down') {
+            rl.clearLine(0); // Clean readline state before navigation
+            const direction = key.name === 'up' ? -1 : 1;
             const selectableIndexes = filteredItems
                 .map((item, index) => ({ item, index }))
                 .filter(({ item }) => isSelectable(item))
@@ -275,14 +344,22 @@ exports.default = (0, core_1.createPrompt)((config, done) => {
             else {
                 nextSelectableIndex = Math.max(0, Math.min(nextSelectableIndex, selectableIndexes.length - 1));
             }
-            setActive(selectableIndexes[nextSelectableIndex] || 0);
+            // Translate from position inside `selectableIndexes` to the real index
+            const nextFilteredIndex = selectableIndexes[nextSelectableIndex];
+            const nextSelectableItem = filteredItems[nextFilteredIndex];
+            if (nextSelectableItem && isSelectable(nextSelectableItem)) {
+                setActiveItemValue(nextSelectableItem.value);
+            }
             return;
         }
-        // Handle selection toggle with tab key ONLY - prevent tab from affecting search text
+        // Handle selection toggle with tab key
         if (key.name === 'tab') {
+            const preservedSearchTerm = searchTerm;
             const activeItem = filteredItems[active];
             if (activeItem && isSelectable(activeItem)) {
                 const activeValue = activeItem.value;
+                // Set this as the active item value so cursor position is preserved
+                setActiveItemValue(activeValue);
                 setAllItems(allItems.map((item) => {
                     // Compare by value only for robust matching
                     if (!core_1.Separator.isSeparator(item) && item.value === activeValue) {
@@ -292,7 +369,10 @@ exports.default = (0, core_1.createPrompt)((config, done) => {
                     return item;
                 }));
             }
-            return; // Important: return here to prevent tab from being added to search term
+            updateSearchTerm(preservedSearchTerm);
+            // return to prevent tab from affecting search text:
+            // Readline's tab completion in @inquirer/core can modify rl.line, adding spaces to the search text
+            return;
         }
         // Handle submission
         if ((0, core_1.isEnterKey)(key)) {
@@ -336,9 +416,18 @@ exports.default = (0, core_1.createPrompt)((config, done) => {
         // Handle all other input as search term updates EXCEPT tab
         // Only update search term for actual typing, not navigation keys
         if (!isNavigationOrAction) {
+            // For general input, only update React state since rl.line is already current
             setSearchTerm(rl.line);
         }
     });
+    // Calculate the active item's description using useMemo for better React patterns
+    const activeDescription = (0, core_1.useMemo)(() => {
+        const activeItem = filteredItems[active];
+        if (activeItem && !core_1.Separator.isSeparator(activeItem)) {
+            return activeItem.description;
+        }
+        return undefined;
+    }, [active, filteredItems]);
     // Create renderItem function that's reactive to current state
     const renderItem = (0, core_1.useMemo)(() => {
         return ({ item, isActive }) => {
@@ -363,32 +452,20 @@ exports.default = (0, core_1.createPrompt)((config, done) => {
             let text = item.name;
             if (isActive) {
                 text = theme.style.highlight(text);
+                // NOTE: Description is now calculated via useMemo, not side-effect mutation
             }
             else if (item.disabled) {
                 text = theme.style.disabled(text);
             }
             line.push(text);
-            // Show disabled reason if item is disabled
+            // Show disabled reason if item is disabled (but no descriptions inline anymore)
             if (item.disabled) {
                 const disabledReason = typeof item.disabled === 'string'
                     ? item.disabled
                     : 'disabled';
                 line.push(theme.style.disabled(`(${disabledReason})`));
             }
-            else if (item.description) {
-                const description = item.description;
-                // If using custom description styling, give full control to user (no parentheses)
-                // If using default styling, add parentheses for backward compatibility
-                const isUsingCustomDescriptionStyle = config.theme?.style?.description !== undefined;
-                if (description) {
-                    if (isUsingCustomDescriptionStyle) {
-                        line.push(theme.style.description(description));
-                    }
-                    else {
-                        line.push(`(${theme.style.description(description)})`);
-                    }
-                }
-            }
+            // NOTE: Removed the inline description display - descriptions now appear at bottom
             return line.join(' ');
         };
     }, [allItems, theme, config.theme]);
@@ -403,12 +480,18 @@ exports.default = (0, core_1.createPrompt)((config, done) => {
     // Render the prompt
     const message = theme.style.message(config.message, status);
     let helpTip = '';
-    if (theme.helpMode === 'always') {
-        const tips = ['Tab to select', 'Enter to submit'];
-        helpTip = `\n${theme.style.help(`(${tips.join(', ')})`)}`;
+    if (theme.helpMode === 'always' && config.instructions !== false) {
+        if (typeof config.instructions === 'string') {
+            helpTip = `\n${theme.style.help(`(${config.instructions})`)}`;
+        }
+        else {
+            const tips = ['Tab to select', 'Enter to submit'];
+            helpTip = `\n${theme.style.help(`(${tips.join(', ')})`)}`;
+        }
     }
     let searchLine = '';
-    if (config.source || searchTerm || status === 'loading') {
+    // Always show search line when search functionality is available (static choices or async source)
+    if (config.source || config.choices || searchTerm || status === 'loading') {
         const searchPrefix = status === 'loading' ? 'Loading...' : 'Search:';
         const styledTerm = searchTerm ? theme.style.searchTerm(searchTerm) : '';
         searchLine = `\n${searchPrefix} ${styledTerm}`;
@@ -430,7 +513,12 @@ exports.default = (0, core_1.createPrompt)((config, done) => {
     else {
         content = `\n${page}`;
     }
-    return `${prefix} ${message}${helpTip}${searchLine}${errorLine}${content}${ansi_escapes_1.default.cursorHide}`;
+    // Add description of active item at the bottom (like original inquirer.js)
+    let descriptionLine = '';
+    if (activeDescription) {
+        descriptionLine = `\n${theme.style.description(activeDescription)}`;
+    }
+    return `${prefix} ${message}${helpTip}${searchLine}${errorLine}${content}${descriptionLine}`;
 });
 // Re-export Separator for convenience
 var core_2 = require("@inquirer/core");

package/dist/esm/index.d.ts

@@ -44,6 +44,12 @@ export type NormalizedChoice<Value> = {
     disabled: boolean | string;
     checked: boolean;
 };
+/**
+ * Calculate dynamic page size based on terminal height
+ * @param fallbackPageSize - Default page size to use if terminal height is not available
+ * @returns Calculated page size
+ */
+export declare function calculateDynamicPageSize(fallbackPageSize: number): number;
 /**
  * Main checkbox-search prompt implementation
  *

package/dist/esm/index.js

@@ -1,4 +1,4 @@
-import { createPrompt, useState, useKeypress, usePagination, useEffect, useRef, useMemo, usePrefix, makeTheme, isUpKey, isDownKey, isEnterKey, Separator, } from '@inquirer/core';
+import { createPrompt, useState, useKeypress, usePagination, useEffect, useRef, useMemo, usePrefix, makeTheme, isEnterKey, Separator, } from '@inquirer/core';
 import colors from 'yoctocolors-cjs';
 import figures from '@inquirer/figures';
 import ansiEscapes from 'ansi-escapes';
@@ -18,7 +18,7 @@ const checkboxSearchTheme = {
         help: colors.dim,
         highlight: colors.cyan,
         searchTerm: colors.cyan,
-        description: colors.dim,
+        description: colors.cyan,
         disabled: colors.dim,
     },
     helpMode: 'always',
@@ -98,6 +98,40 @@ function defaultFilter(items, term) {
             value.includes(searchTerm));
     });
 }
+/**
+ * Calculate dynamic page size based on terminal height
+ * @param fallbackPageSize - Default page size to use if terminal height is not available
+ * @returns Calculated page size
+ */
+export function calculateDynamicPageSize(fallbackPageSize) {
+    let rawPageSize;
+    try {
+        // Get terminal height from process.stdout.rows
+        const terminalHeight = process.stdout.rows;
+        if (!terminalHeight || terminalHeight < 1) {
+            // Fallback to static page size if terminal height is not available
+            rawPageSize = fallbackPageSize;
+        }
+        else {
+            // Reserve space for UI elements:
+            // - 1 line for the prompt message
+            // - 1 line for help instructions
+            // - 1 line for search input (if present)
+            // - 1 line for error messages (if present)
+            // - 1 line for description (if present)
+            // - 1 line for buffer/spacing
+            const reservedLines = 6;
+            // Calculate available lines for choices
+            rawPageSize = terminalHeight - reservedLines;
+        }
+    }
+    catch {
+        // If there's any error accessing terminal dimensions, fallback gracefully
+        rawPageSize = fallbackPageSize;
+    }
+    // Ensure minimum page size for usability and cap maximum to prevent overwhelming display
+    return Math.max(2, Math.min(rawPageSize, 50));
+}
 /**
  * Main checkbox-search prompt implementation
  *
@@ -118,7 +152,15 @@ export default createPrompt((config, done) => {
     // Stable reference for empty array to prevent unnecessary recalculations
     const emptyArray = useMemo(() => [], []);
     // Configuration with defaults
-    const { pageSize = 7, loop = true, required, validate = () => true, default: defaultValues = emptyArray, } = config;
+    const { pageSize: configPageSize, loop = true, required, validate = () => true, default: defaultValues = emptyArray, } = config;
+    // Calculate effective page size (memoized with terminal size tracking)
+    // If pageSize is specified, use it as fixed size
+    // If not specified, use auto-sizing that recalculates when terminal resizes
+    const terminalHeight = process.stdout.rows; // Track terminal size for memoization
+    const pageSize = useMemo(() => configPageSize !== undefined
+        ? configPageSize // Fixed page size
+        : calculateDynamicPageSize(7), // Auto page size with fallback 7
+    [configPageSize, terminalHeight]);
     const theme = makeTheme(checkboxSearchTheme, config.theme);
     // State management hooks
     const [status, setStatus] = useState('idle');
@@ -141,6 +183,8 @@ export default createPrompt((config, done) => {
         }
         return [];
     });
+    // Store the active item value instead of active index
+    const [activeItemValue, setActiveItemValue] = useState(null);
     // Compute filtered items based on search term and filtering logic
     const filteredItems = useMemo(() => {
         // Async source mode - use allItems directly (source handles filtering)
@@ -169,8 +213,48 @@ export default createPrompt((config, done) => {
         }
         return result;
     }, [allItems, searchTerm, config.source, config.filter]);
-    const [active, setActive] = useState(0);
+    // Compute active index from activeItemValue
+    const active = useMemo(() => {
+        if (activeItemValue === null) {
+            // No active item set, default to first selectable
+            const firstSelectableIndex = filteredItems.findIndex((item) => isSelectable(item));
+            return firstSelectableIndex !== -1 ? firstSelectableIndex : 0;
+        }
+        // Find the item with the active value
+        const activeIndex = filteredItems.findIndex((item) => !Separator.isSeparator(item) &&
+            item.value === activeItemValue);
+        if (activeIndex !== -1) {
+            return activeIndex;
+        }
+        // Active item not found in filtered list, default to first selectable
+        const firstSelectableIndex = filteredItems.findIndex((item) => isSelectable(item));
+        return firstSelectableIndex !== -1 ? firstSelectableIndex : 0;
+    }, [filteredItems, activeItemValue]);
+    // Update activeItemValue when active index changes (e.g., when filtering results in auto-focus)
+    useEffect(() => {
+        const activeItem = filteredItems[active];
+        if (activeItem && !Separator.isSeparator(activeItem)) {
+            const currentActiveValue = activeItem
+                .value;
+            if (activeItemValue !== currentActiveValue) {
+                setActiveItemValue(currentActiveValue);
+            }
+        }
+    }, [active, filteredItems, activeItemValue]);
     const [errorMsg, setError] = useState();
+    // Hide cursor on mount, show on unmount (like other inquirer prompts)
+    useEffect(() => {
+        // Hide cursor when prompt starts (only in TTY environments)
+        if (process.stdout.isTTY) {
+            process.stdout.write(ansiEscapes.cursorHide);
+        }
+        // Show cursor when prompt ends (cleanup function)
+        return () => {
+            if (process.stdout.isTTY) {
+                process.stdout.write(ansiEscapes.cursorShow);
+            }
+        };
+    }, []);
     // Handle async source - load data based on search term
     useEffect(() => {
         if (!config.source) {
@@ -207,31 +291,14 @@ export default createPrompt((config, done) => {
     useEffect(() => {
         allItemsRef.current = allItems;
     }, [allItems]);
-    // Reset active index when filtered items change, but preserve cursor position during selection toggles
-    useEffect(() => {
-        // Don't reset cursor position if we're just toggling selection on the same items
-        // Only reset when the actual set of filtered items changes (not their selection state)
-        const currentFilteredValues = filteredItems
-            .filter((item) => !Separator.isSeparator(item))
-            .map((item) => item.value);
-        const activeItem = filteredItems[active];
-        const activeValue = activeItem && !Separator.isSeparator(activeItem)
-            ? activeItem.value
-            : null;
-        // If the currently active item is still in the filtered list, preserve its position
-        if (activeValue && currentFilteredValues.includes(activeValue)) {
-            const newActiveIndex = filteredItems.findIndex((item) => !Separator.isSeparator(item) &&
-                item.value === activeValue);
-            if (newActiveIndex !== -1) {
-                setActive(newActiveIndex);
-                return;
-            }
-        }
-        // Otherwise reset to 0 (when filtering actually changes the set of items)
-        setActive(0);
-    }, [filteredItems, active]);
     // Keyboard event handling
     useKeypress((key, rl) => {
+        // Helper function to update search term in both readline and React state
+        const updateSearchTerm = (newTerm) => {
+            rl.clearLine(0);
+            rl.write(newTerm);
+            setSearchTerm(newTerm);
+        };
         // Allow search input even during loading, but block other actions
         const isNavigationOrAction = key.name === 'up' ||
             key.name === 'down' ||
@@ -245,13 +312,14 @@ export default createPrompt((config, done) => {
         setError(undefined);
         // Handle Escape key - clear search term quickly
         if (key.name === 'escape') {
-            rl.line = ''; // Clear readline input first (avoid re-render)
-            setSearchTerm(''); // Then update state
+            updateSearchTerm(''); // Clear both readline and React state
             return;
         }
-        // Handle navigation
-        if (isUpKey(key) || isDownKey(key)) {
-            const direction = isUpKey(key) ? -1 : 1;
+        // Handle navigation - ONLY actual arrow keys (not vim j/k keys)
+        // This follows the official inquirer.js search approach
+        if (key.name === 'up' || key.name === 'down') {
+            rl.clearLine(0); // Clean readline state before navigation
+            const direction = key.name === 'up' ? -1 : 1;
             const selectableIndexes = filteredItems
                 .map((item, index) => ({ item, index }))
                 .filter(({ item }) => isSelectable(item))
@@ -269,14 +337,22 @@ export default createPrompt((config, done) => {
             else {
                 nextSelectableIndex = Math.max(0, Math.min(nextSelectableIndex, selectableIndexes.length - 1));
             }
-            setActive(selectableIndexes[nextSelectableIndex] || 0);
+            // Translate from position inside `selectableIndexes` to the real index
+            const nextFilteredIndex = selectableIndexes[nextSelectableIndex];
+            const nextSelectableItem = filteredItems[nextFilteredIndex];
+            if (nextSelectableItem && isSelectable(nextSelectableItem)) {
+                setActiveItemValue(nextSelectableItem.value);
+            }
             return;
         }
-        // Handle selection toggle with tab key ONLY - prevent tab from affecting search text
+        // Handle selection toggle with tab key
         if (key.name === 'tab') {
+            const preservedSearchTerm = searchTerm;
             const activeItem = filteredItems[active];
             if (activeItem && isSelectable(activeItem)) {
                 const activeValue = activeItem.value;
+                // Set this as the active item value so cursor position is preserved
+                setActiveItemValue(activeValue);
                 setAllItems(allItems.map((item) => {
                     // Compare by value only for robust matching
                     if (!Separator.isSeparator(item) && item.value === activeValue) {
@@ -286,7 +362,10 @@ export default createPrompt((config, done) => {
                     return item;
                 }));
             }
-            return; // Important: return here to prevent tab from being added to search term
+            updateSearchTerm(preservedSearchTerm);
+            // return to prevent tab from affecting search text:
+            // Readline's tab completion in @inquirer/core can modify rl.line, adding spaces to the search text
+            return;
         }
         // Handle submission
         if (isEnterKey(key)) {
@@ -330,9 +409,18 @@ export default createPrompt((config, done) => {
         // Handle all other input as search term updates EXCEPT tab
         // Only update search term for actual typing, not navigation keys
         if (!isNavigationOrAction) {
+            // For general input, only update React state since rl.line is already current
             setSearchTerm(rl.line);
         }
     });
+    // Calculate the active item's description using useMemo for better React patterns
+    const activeDescription = useMemo(() => {
+        const activeItem = filteredItems[active];
+        if (activeItem && !Separator.isSeparator(activeItem)) {
+            return activeItem.description;
+        }
+        return undefined;
+    }, [active, filteredItems]);
     // Create renderItem function that's reactive to current state
     const renderItem = useMemo(() => {
         return ({ item, isActive }) => {
@@ -357,32 +445,20 @@ export default createPrompt((config, done) => {
             let text = item.name;
             if (isActive) {
                 text = theme.style.highlight(text);
+                // NOTE: Description is now calculated via useMemo, not side-effect mutation
             }
             else if (item.disabled) {
                 text = theme.style.disabled(text);
             }
             line.push(text);
-            // Show disabled reason if item is disabled
+            // Show disabled reason if item is disabled (but no descriptions inline anymore)
             if (item.disabled) {
                 const disabledReason = typeof item.disabled === 'string'
                     ? item.disabled
                     : 'disabled';
                 line.push(theme.style.disabled(`(${disabledReason})`));
             }
-            else if (item.description) {
-                const description = item.description;
-                // If using custom description styling, give full control to user (no parentheses)
-                // If using default styling, add parentheses for backward compatibility
-                const isUsingCustomDescriptionStyle = config.theme?.style?.description !== undefined;
-                if (description) {
-                    if (isUsingCustomDescriptionStyle) {
-                        line.push(theme.style.description(description));
-                    }
-                    else {
-                        line.push(`(${theme.style.description(description)})`);
-                    }
-                }
-            }
+            // NOTE: Removed the inline description display - descriptions now appear at bottom
             return line.join(' ');
         };
     }, [allItems, theme, config.theme]);
@@ -397,12 +473,18 @@ export default createPrompt((config, done) => {
     // Render the prompt
     const message = theme.style.message(config.message, status);
     let helpTip = '';
-    if (theme.helpMode === 'always') {
-        const tips = ['Tab to select', 'Enter to submit'];
-        helpTip = `\n${theme.style.help(`(${tips.join(', ')})`)}`;
+    if (theme.helpMode === 'always' && config.instructions !== false) {
+        if (typeof config.instructions === 'string') {
+            helpTip = `\n${theme.style.help(`(${config.instructions})`)}`;
+        }
+        else {
+            const tips = ['Tab to select', 'Enter to submit'];
+            helpTip = `\n${theme.style.help(`(${tips.join(', ')})`)}`;
+        }
     }
     let searchLine = '';
-    if (config.source || searchTerm || status === 'loading') {
+    // Always show search line when search functionality is available (static choices or async source)
+    if (config.source || config.choices || searchTerm || status === 'loading') {
         const searchPrefix = status === 'loading' ? 'Loading...' : 'Search:';
         const styledTerm = searchTerm ? theme.style.searchTerm(searchTerm) : '';
         searchLine = `\n${searchPrefix} ${styledTerm}`;
@@ -424,7 +506,12 @@ export default createPrompt((config, done) => {
     else {
         content = `\n${page}`;
     }
-    return `${prefix} ${message}${helpTip}${searchLine}${errorLine}${content}${ansiEscapes.cursorHide}`;
+    // Add description of active item at the bottom (like original inquirer.js)
+    let descriptionLine = '';
+    if (activeDescription) {
+        descriptionLine = `\n${theme.style.description(activeDescription)}`;
+    }
+    return `${prefix} ${message}${helpTip}${searchLine}${errorLine}${content}${descriptionLine}`;
 });
 // Re-export Separator for convenience
 export { Separator } from '@inquirer/core';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inquirerjs-checkbox-search",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "A multi-select prompt with text filtering for inquirer.js",
   "keywords": [
     "answer",
@@ -64,7 +64,7 @@
   ],
   "scripts": {
     "build": "tshy",
-    "clean": "rimraf dist .tshy",
+    "clean": "rimraf dist .tshy .tshy-build package-inspect coverage src/node_modules",
     "dev": "tshy --watch",
     "lint": "eslint . --ext .ts --fix",
     "lint:check": "eslint . --ext .ts",
@@ -84,7 +84,7 @@
     "@inquirer/core": "^10.1.13",
     "@inquirer/figures": "^1.0.12",
     "@inquirer/type": "^3.0.7",
-    "ansi-escapes": "^4.3.2",
+    "ansi-escapes": "^7.0.0",
     "yoctocolors-cjs": "^2.1.2"
   },
   "devDependencies": {
@@ -93,15 +93,15 @@
     "@types/node": "^20.0.0",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "@typescript-eslint/parser": "^8.0.0",
-    "@vitest/coverage-v8": "^2.0.0",
-    "@vitest/ui": "^2.0.0",
+    "@vitest/coverage-v8": "^3.2.3",
+    "@vitest/ui": "^3.2.3",
     "eslint": "^9.0.0",
     "eslint-config-prettier": "^9.0.0",
     "prettier": "^3.0.0",
     "rimraf": "^6.0.0",
     "tshy": "^3.0.2",
     "typescript": "^5.6.0",
-    "vitest": "^2.0.0"
+    "vitest": "^3.2.3"
   },
   "engines": {
     "node": ">=18"