inquirerjs-checkbox-search 0.1.2 → 0.3.0

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 \| PageSizeConfig`                                                          | No       | Page size configuration. Can be a number (fixed size) or PageSizeConfig object for advanced control. 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.
 
@@ -94,6 +67,33 @@ type Choice<Value = any> = {
 };
 ```
 
+### PageSize Configuration
+
+The `pageSize` property accepts either a number (for simple fixed sizing) or a `PageSizeConfig` object for advanced control:
+
+```typescript
+type PageSizeConfig = {
+  base?: number; // Starting page size (if not specified, auto-calculated from terminal)
+  max?: number; // Maximum page size (absolute constraint)
+  min?: number; // Minimum page size (absolute constraint, defaults to 1)
+  buffer?: number; // Fixed buffer lines to subtract from page size
+  autoBufferDescriptions?: boolean; // Auto-reserve space for descriptions
+  autoBufferCountsLineWidth?: boolean; // Consider terminal width when counting description lines
+  minBuffer?: number; // Minimum buffer lines (applied after auto/manual buffer)
+};
+```
+
+**Buffer Calculation Process:**
+
+1. Start with base page size (from `base` or auto-calculated)
+2. Calculate buffer:
+   - If `autoBufferDescriptions` is true: Add lines needed for largest description
+   - Otherwise: Add `buffer` value (if specified)
+   - Ensure buffer is at least `minBuffer` (if specified)
+3. Subtract buffer from base page size
+4. Apply `min`/`max` constraints
+5. Ensure final result is at least 1
+
 ### Theme Options
 
 ```typescript
@@ -129,21 +129,7 @@ type CheckboxSearchTheme = {
 
 ## Advanced Features
 
-For detailed examples of advanced features, see the [`examples/`](./examples/) directory:
-
-- **[Basic Multi-Select](./examples/basic.js)** - Simple multi-select functionality
-- **[Search Filtering](./examples/search-filtering.js)** - Real-time search with larger lists
-- **[Async Source](./examples/async-source.js)** - Dynamic loading with mock API
-- **[Custom Theme](./examples/custom-theme.js)** - Custom icons and styling
-- **[Validation](./examples/validation.js)** - Input validation and pre-selection
-- **[Custom Filter](./examples/custom-filter.js)** - Fuzzy matching filter
-
-**To run examples:**
-
-1. Build the package: `npm run build`
-2. Run any example: `node examples/basic.js`
-
-See the [examples README](./examples/README.md) for detailed instructions.
+For detailed examples of advanced features, see the [`examples/`](./examples/) directory.
 
 Each example includes detailed comments and demonstrates real-world usage patterns.
 

package/dist/commonjs/index.d.ts

@@ -44,6 +44,49 @@ export type NormalizedChoice<Value> = {
     disabled: boolean | string;
     checked: boolean;
 };
+/**
+ * Configuration options for the checkbox-search prompt
+ */
+export type PageSizeConfig = {
+    base?: number;
+    max?: number;
+    min?: number;
+    autoBufferDescriptions?: boolean;
+    buffer?: number;
+    minBuffer?: number;
+    autoBufferCountsLineWidth?: boolean;
+};
+export type PageSize = number | PageSizeConfig;
+/**
+ * Internal item type (choice or separator)
+ */
+type Item<Value> = NormalizedChoice<Value> | Separator;
+/**
+ * Validate PageSizeConfig object for correctness
+ * @param config - PageSizeConfig to validate
+ * @throws Error if validation fails
+ */
+export declare function validatePageSizeConfig(config: PageSizeConfig): void;
+/**
+ * Calculate the maximum number of lines needed for descriptions across all items
+ * @param items - Array of items to analyze
+ * @param countLineWidth - Whether to consider terminal width for line wrapping
+ * @returns Maximum lines needed by any description
+ */
+export declare function calculateDescriptionLines<Value>(items: readonly Item<Value>[], countLineWidth: boolean): number;
+/**
+ * Resolve PageSize configuration to a final numeric page size
+ * @param pageSize - PageSize configuration (number or PageSizeConfig)
+ * @param items - Current items to consider for auto-buffering
+ * @returns Final resolved page size
+ */
+export declare function resolvePageSize<Value>(pageSize: PageSize, items: readonly Item<Value>[]): number;
+/**
+ * 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
  *
@@ -63,7 +106,7 @@ export type NormalizedChoice<Value> = {
 declare const _default: <Value>(config: {
     message: string;
     prefix?: string | undefined;
-    pageSize?: number | undefined;
+    pageSize?: PageSize | undefined;
     instructions?: string | boolean | undefined;
     choices?: readonly (string | Separator)[] | readonly (Separator | Choice<Value>)[] | undefined;
     source?: ((term: string | undefined, opt: {

package/dist/commonjs/index.js

@@ -4,6 +4,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Separator = void 0;
+exports.validatePageSizeConfig = validatePageSizeConfig;
+exports.calculateDescriptionLines = calculateDescriptionLines;
+exports.resolvePageSize = resolvePageSize;
+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 +28,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 +108,142 @@ function defaultFilter(items, term) {
             value.includes(searchTerm));
     });
 }
+/**
+ * Validate PageSizeConfig object for correctness
+ * @param config - PageSizeConfig to validate
+ * @throws Error if validation fails
+ */
+function validatePageSizeConfig(config) {
+    if (config.min !== undefined && config.min < 1) {
+        throw new Error('PageSize min cannot be less than 1');
+    }
+    if (config.base !== undefined && config.base < 1) {
+        throw new Error('PageSize base cannot be less than 1');
+    }
+    if (config.buffer !== undefined && config.buffer < 0) {
+        throw new Error('PageSize buffer cannot be negative');
+    }
+    if (config.minBuffer !== undefined && config.minBuffer < 0) {
+        throw new Error('PageSize minBuffer cannot be negative');
+    }
+    if (config.min !== undefined &&
+        config.max !== undefined &&
+        config.min > config.max) {
+        throw new Error(`PageSize min (${config.min}) cannot be greater than max (${config.max})`);
+    }
+}
+/**
+ * Calculate the maximum number of lines needed for descriptions across all items
+ * @param items - Array of items to analyze
+ * @param countLineWidth - Whether to consider terminal width for line wrapping
+ * @returns Maximum lines needed by any description
+ */
+function calculateDescriptionLines(items, countLineWidth) {
+    let maxLines = 0;
+    for (const item of items) {
+        if (core_1.Separator.isSeparator(item) || !item.description) {
+            continue;
+        }
+        let lines;
+        if (countLineWidth) {
+            // Consider terminal width for wrapping
+            const terminalWidth = process.stdout.columns || 80;
+            const descriptionLines = item.description.split('\n');
+            lines = descriptionLines.reduce((total, line) => {
+                return total + (Math.ceil(line.length / terminalWidth) || 1);
+            }, 0);
+        }
+        else {
+            // Simple newline counting
+            lines = item.description.split('\n').length;
+        }
+        maxLines = Math.max(maxLines, lines);
+    }
+    return maxLines;
+}
+/**
+ * Resolve PageSize configuration to a final numeric page size
+ * @param pageSize - PageSize configuration (number or PageSizeConfig)
+ * @param items - Current items to consider for auto-buffering
+ * @returns Final resolved page size
+ */
+function resolvePageSize(pageSize, items) {
+    // Handle simple number case (backward compatibility)
+    if (typeof pageSize === 'number') {
+        return pageSize;
+    }
+    // Validate the configuration
+    validatePageSizeConfig(pageSize);
+    // Step 1: Determine base page size
+    let basePageSize;
+    if (pageSize.base !== undefined) {
+        basePageSize = pageSize.base;
+    }
+    else {
+        // Auto-calculate using existing logic
+        basePageSize = calculateDynamicPageSize(7);
+    }
+    // Step 2: Calculate buffer reduction
+    let buffer = 0;
+    // 2a: Start at 0 ✓
+    // 2b: If autoBufferDescriptions, add max description lines
+    if (pageSize.autoBufferDescriptions) {
+        buffer += calculateDescriptionLines(items, pageSize.autoBufferCountsLineWidth || false);
+    }
+    else {
+        // 2c: Add buffer value (only if not auto-buffering)
+        buffer += pageSize.buffer || 0;
+    }
+    // 2d: Ensure at least minBuffer
+    if (pageSize.minBuffer !== undefined) {
+        buffer = Math.max(buffer, pageSize.minBuffer);
+    }
+    // Step 3: Subtract buffer from base
+    let finalPageSize = basePageSize - buffer;
+    // Step 4: Apply min/max constraints
+    if (pageSize.min !== undefined) {
+        finalPageSize = Math.max(finalPageSize, pageSize.min);
+    }
+    if (pageSize.max !== undefined) {
+        finalPageSize = Math.min(finalPageSize, pageSize.max);
+    }
+    // Ensure minimum of 1
+    return Math.max(1, finalPageSize);
+}
+/**
+ * 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 +264,7 @@ 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;
     const theme = (0, core_1.makeTheme)(checkboxSearchTheme, config.theme);
     // State management hooks
     const [status, setStatus] = (0, core_1.useState)('idle');
@@ -147,6 +287,20 @@ exports.default = (0, core_1.createPrompt)((config, done) => {
         }
         return [];
     });
+    // Calculate effective page size (memoized with terminal size tracking)
+    // Use new resolvePageSize function to handle both number and PageSizeConfig
+    const terminalHeight = process.stdout.rows; // Track terminal size for memoization
+    const pageSize = (0, core_1.useMemo)(() => {
+        if (configPageSize !== undefined) {
+            return resolvePageSize(configPageSize, allItems);
+        }
+        else {
+            // Default behavior - auto-calculate
+            return calculateDynamicPageSize(7);
+        }
+    }, [configPageSize, terminalHeight, allItems]);
+    // 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 +329,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 +407,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 +428,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 +453,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 +478,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 +525,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 +561,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 +589,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 +622,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,49 @@ export type NormalizedChoice<Value> = {
     disabled: boolean | string;
     checked: boolean;
 };
+/**
+ * Configuration options for the checkbox-search prompt
+ */
+export type PageSizeConfig = {
+    base?: number;
+    max?: number;
+    min?: number;
+    autoBufferDescriptions?: boolean;
+    buffer?: number;
+    minBuffer?: number;
+    autoBufferCountsLineWidth?: boolean;
+};
+export type PageSize = number | PageSizeConfig;
+/**
+ * Internal item type (choice or separator)
+ */
+type Item<Value> = NormalizedChoice<Value> | Separator;
+/**
+ * Validate PageSizeConfig object for correctness
+ * @param config - PageSizeConfig to validate
+ * @throws Error if validation fails
+ */
+export declare function validatePageSizeConfig(config: PageSizeConfig): void;
+/**
+ * Calculate the maximum number of lines needed for descriptions across all items
+ * @param items - Array of items to analyze
+ * @param countLineWidth - Whether to consider terminal width for line wrapping
+ * @returns Maximum lines needed by any description
+ */
+export declare function calculateDescriptionLines<Value>(items: readonly Item<Value>[], countLineWidth: boolean): number;
+/**
+ * Resolve PageSize configuration to a final numeric page size
+ * @param pageSize - PageSize configuration (number or PageSizeConfig)
+ * @param items - Current items to consider for auto-buffering
+ * @returns Final resolved page size
+ */
+export declare function resolvePageSize<Value>(pageSize: PageSize, items: readonly Item<Value>[]): number;
+/**
+ * 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
  *
@@ -63,7 +106,7 @@ export type NormalizedChoice<Value> = {
 declare const _default: <Value>(config: {
     message: string;
     prefix?: string | undefined;
-    pageSize?: number | undefined;
+    pageSize?: PageSize | undefined;
     instructions?: string | boolean | undefined;
     choices?: readonly (string | Separator)[] | readonly (Separator | Choice<Value>)[] | undefined;
     source?: ((term: string | undefined, opt: {

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,142 @@ function defaultFilter(items, term) {
             value.includes(searchTerm));
     });
 }
+/**
+ * Validate PageSizeConfig object for correctness
+ * @param config - PageSizeConfig to validate
+ * @throws Error if validation fails
+ */
+export function validatePageSizeConfig(config) {
+    if (config.min !== undefined && config.min < 1) {
+        throw new Error('PageSize min cannot be less than 1');
+    }
+    if (config.base !== undefined && config.base < 1) {
+        throw new Error('PageSize base cannot be less than 1');
+    }
+    if (config.buffer !== undefined && config.buffer < 0) {
+        throw new Error('PageSize buffer cannot be negative');
+    }
+    if (config.minBuffer !== undefined && config.minBuffer < 0) {
+        throw new Error('PageSize minBuffer cannot be negative');
+    }
+    if (config.min !== undefined &&
+        config.max !== undefined &&
+        config.min > config.max) {
+        throw new Error(`PageSize min (${config.min}) cannot be greater than max (${config.max})`);
+    }
+}
+/**
+ * Calculate the maximum number of lines needed for descriptions across all items
+ * @param items - Array of items to analyze
+ * @param countLineWidth - Whether to consider terminal width for line wrapping
+ * @returns Maximum lines needed by any description
+ */
+export function calculateDescriptionLines(items, countLineWidth) {
+    let maxLines = 0;
+    for (const item of items) {
+        if (Separator.isSeparator(item) || !item.description) {
+            continue;
+        }
+        let lines;
+        if (countLineWidth) {
+            // Consider terminal width for wrapping
+            const terminalWidth = process.stdout.columns || 80;
+            const descriptionLines = item.description.split('\n');
+            lines = descriptionLines.reduce((total, line) => {
+                return total + (Math.ceil(line.length / terminalWidth) || 1);
+            }, 0);
+        }
+        else {
+            // Simple newline counting
+            lines = item.description.split('\n').length;
+        }
+        maxLines = Math.max(maxLines, lines);
+    }
+    return maxLines;
+}
+/**
+ * Resolve PageSize configuration to a final numeric page size
+ * @param pageSize - PageSize configuration (number or PageSizeConfig)
+ * @param items - Current items to consider for auto-buffering
+ * @returns Final resolved page size
+ */
+export function resolvePageSize(pageSize, items) {
+    // Handle simple number case (backward compatibility)
+    if (typeof pageSize === 'number') {
+        return pageSize;
+    }
+    // Validate the configuration
+    validatePageSizeConfig(pageSize);
+    // Step 1: Determine base page size
+    let basePageSize;
+    if (pageSize.base !== undefined) {
+        basePageSize = pageSize.base;
+    }
+    else {
+        // Auto-calculate using existing logic
+        basePageSize = calculateDynamicPageSize(7);
+    }
+    // Step 2: Calculate buffer reduction
+    let buffer = 0;
+    // 2a: Start at 0 ✓
+    // 2b: If autoBufferDescriptions, add max description lines
+    if (pageSize.autoBufferDescriptions) {
+        buffer += calculateDescriptionLines(items, pageSize.autoBufferCountsLineWidth || false);
+    }
+    else {
+        // 2c: Add buffer value (only if not auto-buffering)
+        buffer += pageSize.buffer || 0;
+    }
+    // 2d: Ensure at least minBuffer
+    if (pageSize.minBuffer !== undefined) {
+        buffer = Math.max(buffer, pageSize.minBuffer);
+    }
+    // Step 3: Subtract buffer from base
+    let finalPageSize = basePageSize - buffer;
+    // Step 4: Apply min/max constraints
+    if (pageSize.min !== undefined) {
+        finalPageSize = Math.max(finalPageSize, pageSize.min);
+    }
+    if (pageSize.max !== undefined) {
+        finalPageSize = Math.min(finalPageSize, pageSize.max);
+    }
+    // Ensure minimum of 1
+    return Math.max(1, finalPageSize);
+}
+/**
+ * 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 +254,7 @@ 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;
     const theme = makeTheme(checkboxSearchTheme, config.theme);
     // State management hooks
     const [status, setStatus] = useState('idle');
@@ -141,6 +277,20 @@ export default createPrompt((config, done) => {
         }
         return [];
     });
+    // Calculate effective page size (memoized with terminal size tracking)
+    // Use new resolvePageSize function to handle both number and PageSizeConfig
+    const terminalHeight = process.stdout.rows; // Track terminal size for memoization
+    const pageSize = useMemo(() => {
+        if (configPageSize !== undefined) {
+            return resolvePageSize(configPageSize, allItems);
+        }
+        else {
+            // Default behavior - auto-calculate
+            return calculateDynamicPageSize(7);
+        }
+    }, [configPageSize, terminalHeight, allItems]);
+    // 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 +319,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 +397,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 +418,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 +443,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 +468,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 +515,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 +551,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 +579,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 +612,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.3.0",
   "description": "A multi-select prompt with text filtering for inquirer.js",
   "keywords": [
     "answer",
@@ -64,14 +64,16 @@
   ],
   "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",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "test": "npm run format && npm run lint && npm run typecheck && npm run test:unit",
-    "test:ci": "npm run format:check && npm run lint:check && npm run typecheck && npm run test:unit",
+    "quality": "npm run format && npm run lint && npm run typecheck",
+    "quality:check": "npm run format:check && npm run lint:check && npm run typecheck",
+    "test": "npm run quality && npm run test:unit",
+    "test:ci": "npm run quality:check && npm run test:coverage",
     "test:unit": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:ui": "vitest --ui",
@@ -84,7 +86,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 +95,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"